contributing.md 4.9 KB
Newer Older
T
Tim Neutkens 已提交
1 2
# Contributing to Next.js

T
Tim Neutkens 已提交
3
Our Commitment to Open Source can be found [here](https://vercel.com/blog/oss)
T
Tim Neutkens 已提交
4 5

1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
6 7 8 9 10 11
2. Create a new branch `git checkout -b MY_BRANCH_NAME`
3. Install yarn: `npm install -g yarn`
4. Install the dependencies: `yarn`
5. Run `yarn dev` to build and watch for code changes
6. In a new terminal, run `yarn types` to compile declaration files from TypeScript
7. The development branch is `canary` (this is the branch pull requests should be made against). On a release, the relevant parts of the changes in the `canary` branch are rebased into `master`.
12 13

> You may need to run `yarn types` again if your types get outdated.
14

15 16
To contribute to [our examples](examples), take a look at the [“Adding examples” section](#adding-examples).

17
## To run tests
18

19 20
Make sure you have `chromedriver` installed for your Chrome version. You can install it with

T
Tim Neutkens 已提交
21
- `brew cask install chromedriver` on Mac OS X
22
- `chocolatey install chromedriver` on Windows
23
- Or manually download the version that matches your installed chrome version (if there's no match, download a version under it, but not above) from the [chromedriver repo](https://chromedriver.storage.googleapis.com/index.html) and add the binary to `<next-repo>/node_modules/.bin`
24

25 26
Running all tests:

27
```sh
28 29 30
yarn testonly
```

31 32 33 34 35 36 37 38 39 40 41 42
If you would like to run the tests in headless mode (with the browser windows hidden) you can do

```sh
yarn testheadless
```

If you would like to use a specific Chrome/Chromium binary to run tests you can specify it with

```sh
CHROME_BIN='path/to/chrome/bin' yarn testonly
```

43 44
Running a specific test suite inside of the `test/integration` directory:

45
```sh
46 47 48 49 50
yarn testonly --testPathPattern "production"
```

Running just one test in the `production` test suite:

51
```sh
52 53 54
yarn testonly --testPathPattern "production" -t "should allow etag header support"
```

55
## Running the integration apps
56

57
Running examples can be done with:
58

59
```sh
60
yarn next ./test/integration/basic
61
# OR
62
yarn next ./examples/basic-css/
63
```
64 65 66 67 68 69 70 71 72 73 74 75 76 77

To figure out which pages are available for the given example, you can run:

```sh
EXAMPLE=./test/integration/basic
(\
  cd $EXAMPLE/pages; \
  find . -type f \
  | grep -v '\.next' \
  | sed 's#^\.##' \
  | sed 's#index\.js##' \
  | sed 's#\.js$##' \
  | xargs -I{} echo localhost:3000{} \
)
78 79
```

80
## Running your own app with locally compiled version of Next.js
81

82
1. In your app's `package.json`, replace:
83

84 85 86
   ```json
   "next": "<next-version>",
   ```
87

88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
   with:

   ```json
   "next": "file:<local-path-to-cloned-nextjs-repo>/packages/next",
   ```

2. In your app's root directory, make sure to remove `next` from `node_modules` with:

   ```sh
   rm -rf ./node_modules/next
   ```

3. In your app's root directory, run:

   ```sh
   yarn
   ```

   to re-install all of the dependencies.

   Note that Next will be copied from the locally compiled version as opposed to from being downloaded from the NPM registry.

4. Run your application as you normally would.
111 112 113 114 115 116

5. To update your app's dependencies, after you've made changes to your local `next` repository. In your app's root directory, run:

   ```sh
   yarn install --force
   ```
117 118 119 120 121 122 123 124 125

## Adding examples

When you add an example to the [examples](examples) directory, don’t forget to add a `README.md` file with the following format:

- Replace `DIRECTORY_NAME` with the directory name you’re adding.
- Fill in `Example Name` and `Description`.
- To add additional installation instructions, please add it where appropriate.
- To add additional notes, add `## Notes` section at the end.
T
Tim Neutkens 已提交
126
- Remove the `Deploy your own` section if your example can’t be immediately deployed to Vercel.
127 128 129 130 131 132 133 134

````markdown
# Example Name

Description

## Deploy your own

T
Tim Neutkens 已提交
135
Deploy the example using [Vercel](https://vercel.com/now):
136

T
Tim Neutkens 已提交
137
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/DIRECTORY_NAME)
138 139 140 141 142 143 144 145

## How to use

### Using `create-next-app`

Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:

```bash
146
npm init next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169
# or
yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
```

### Download manually

Download the example:

```bash
curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/DIRECTORY_NAME
cd DIRECTORY_NAME
```

Install it and run:

```bash
npm install
npm run dev
# or
yarn
yarn dev
```

T
Tim Neutkens 已提交
170
Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
171
````