Skip to content

Latest commit

 

History

History
171 lines (117 loc) · 4.9 KB

contributing.md

File metadata and controls

171 lines (117 loc) · 4.9 KB
Raw

Contributing to Next.js

Our Commitment to Open Source can be found here

  1. Fork this repository to your own GitHub account and then clone it to your local device.
  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.

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

To contribute to our examples, take a look at the “Adding examples” section.

To run tests

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

  • brew cask install chromedriver on Mac OS X
  • chocolatey install chromedriver on Windows
  • 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 and add the binary to <next-repo>/node_modules/.bin

Running all tests:

yarn testonly

If you would like to run the tests in headless mode (with the browser windows hidden) you can do

yarn testheadless

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

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

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

yarn testonly --testPathPattern "production"

Running just one test in the production test suite:

yarn testonly --testPathPattern "production" -t "should allow etag header support"

Running the integration apps

Running examples can be done with:

yarn next ./test/integration/basic
# OR
yarn next ./examples/basic-css/

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

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{} \
)

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

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

    "next": "<next-version>",

    with:

    "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:

    rm -rf ./node_modules/next

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

    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.

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

    yarn install --force

Adding examples

When you add an example to the 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.
  • Remove the Deploy your own section if your example can’t be immediately deployed to ZEIT Now.
# Example Name

Description

## Deploy your own

Deploy the example using [ZEIT Now](https://zeit.co/now):

[![Deploy with ZEIT Now](https://zeit.co/button)](https://zeit.co/import/project?template=https://github.com/zeit/next.js/tree/canary/examples/DIRECTORY_NAME)

## 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
npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app
# 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
```

Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).