Read about our [Commitment to Open Source](https://vercel.com/oss). To
[Watch the 40-minute walkthrough video on how to contribute to Next.js.](https://www.youtube.com/watch?v=cuoNzXFLitc)
contribute to [our examples](examples), please see **[Adding
examples](#adding-examples)** below.
Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission.
---
- Read about our [Commitment to Open Source](https://vercel.com/oss).
- To contribute to [our examples](examples), please see [Adding examples](#adding-examples) below.
- Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission.
@@ -48,7 +48,7 @@ Or add a `className` to the `body` tag:
...
@@ -48,7 +48,7 @@ Or add a `className` to the `body` tag:
> **Note:** This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
> **Note:** This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
To prepare for [React 18](/docs/advanced-features/react-18.md), we recommend avoiding customizing `getInitiaProps` and `renderPage`, if possible.
To prepare for [React 18](/docs/advanced-features/react-18.md), we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible.
The `ctx` object shown below is equivalent to the one received in [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md#context-object), with the addition of `renderPage`.
The `ctx` object shown below is equivalent to the one received in [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md#context-object), with the addition of `renderPage`.
@@ -155,7 +155,22 @@ The above generates the following `HTML`:
...
@@ -155,7 +155,22 @@ The above generates the following `HTML`:
</ul>
</ul>
```
```
When you want to style your own elements to give a custom feel to your website or application, you can pass in shortcodes. These are your own custom components that map to `HTML` elements. To do this you use the `MDXProvider` and pass a components object as a prop. Each object key in the components object maps to a `HTML` element name. You also need to specify `providerImportSource: "@mdx-js/react"` in `next.config.js`.
When you want to style your own elements to give a custom feel to your website or application, you can pass in shortcodes. These are your own custom components that map to `HTML` elements. To do this you use the `MDXProvider` and pass a components object as a prop. Each object key in the components object maps to a `HTML` element name.
To enable you need to specify `providerImportSource: "@mdx-js/react"` in `next.config.js`.
```js
// next.config.js
const withMDX = require('@next/mdx')({
// ...
options: {
providerImportSource: '@mdx-js/react',
},
})
```
Then setup the provider in your page
```jsx
```jsx
// pages/index.js
// pages/index.js
...
@@ -186,6 +201,8 @@ export default function Post(props) {
...
@@ -186,6 +201,8 @@ export default function Post(props) {
}
}
```
```
If you use it across the site you may want to add the provider to `_app.js` so all MDX pages pick up the custom element config.
@@ -97,7 +97,35 @@ As `getStaticProps` runs only on the server-side, it will never run on the clien
...
@@ -97,7 +97,35 @@ As `getStaticProps` runs only on the server-side, it will never run on the clien
This means that instead of fetching an **API route** from `getStaticProps` (that itself fetches data from an external source), you can write the server-side code directly in `getStaticProps`.
This means that instead of fetching an **API route** from `getStaticProps` (that itself fetches data from an external source), you can write the server-side code directly in `getStaticProps`.
Take the following example. An API route is used to fetch some data from a CMS. That API route is then called directly from `getStaticProps`. This produces an additional call, reducing performance. Instead, the logic for fetching the data from the CMS can be moved to `getStaticProps`.
Take the following example. An API route is used to fetch some data from a CMS. That API route is then called directly from `getStaticProps`. This produces an additional call, reducing performance. Instead, the logic for fetching the data from the CMS can be shared by using a `lib/` directory. Then it can be shared with `getStaticProps`.
```jsx
// lib/fetch-posts.js
// The following function is shared
// with getStaticProps and API routes
// from a `lib/` directory
exportasyncfunctionloadPosts(){
// Call an external API endpoint to get posts
constres=awaitfetch('https://.../posts/')
constdata=awaitres.json()
returndata
}
// pages/blog.js
import{loadPosts}from'../lib/load-posts'
// This function runs only on the server side
exportasyncfunctiongetStaticProps(){
// Instead of fetching your `/api` route you can call the same
// function directly in `getStaticProps`
constposts=awaitloadPosts()
// Props returned will be passed to the page component
return{props:{posts}}
}
```
Alternatively, if you are **not** using API routes to fetch data, then the [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API _can_ be used directly in `getStaticProps` to fetch data.
Alternatively, if you are **not** using API routes to fetch data, then the [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API _can_ be used directly in `getStaticProps` to fetch data.
Depending on the environment (as set by `NODE_ENV`), variables are loaded from the following sources in order from top-to-bottom. In all environments existing env is not overridden by following sources.
Depending on the environment (as set by `NODE_ENV`), Environment Variables are loaded from the following sources in top-to-bottom order. In all environments, the existing `env` is not overridden by following sources:
`NODE_ENV=production`
`NODE_ENV=production`
-`.env.production.local`
1.`.env.production.local`
-`.env.local`
1.`.env.local`
-`.env.production`
1.`.env.production`
-`.env`
1.`.env`
`NODE_ENV=development`
`NODE_ENV=development`
-`.env.development.local`
1.`.env.development.local`
-`.env.local`
1.`.env.local`
-`.env.development`
1.`.env.development`
-`.env`
1.`.env`
`NODE_ENV=test`
`NODE_ENV=test`
-`.env.test.local`
1.`.env.test.local`
-`.env.test`
1.`.env.test`
-`.env`
1.`.env`
_(note: `.env.local` is not loaded when `NODE_ENV=test`)_
> **Note:** `.env.local` is not loaded when `NODE_ENV=test`.
@@ -33,10 +33,10 @@ The front-end looks like this:
...
@@ -33,10 +33,10 @@ The front-end looks like this:
The HTML `<form>` tag acts as a container for different `<input>` elements like `text` field and submit `button`. Let's study each of these elements:
The HTML `<form>` tag acts as a container for different `<input>` elements like `text` field and submit `button`. Let's study each of these elements:
-`action`: An attribute that specifies where the form data is sent when the form is submitted. It's generally a URL (an absolute URL or a relative URL).
-`action`: An attribute that specifies where the form data is sent when the form is submitted. It's generally a URL (an absolute URL or a relative URL).
-`method`: Specifies the HTTP method, i.e., `GET` or `POST` used to send data while submitting the form.
-`method`: Specifies the [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods), i.e., `GET` or `POST` used to send data while submitting the form.
-`<label>`: An element that defines the label for other form elements. Label aids accessibility, especially for screen readers.
-`<label>`: An element that defines the label for other form elements. Labels aid accessibility, especially for screen readers.
-`<input>`: The form element that is widely used to structure the form fields. It depends significantly on the value of the `type` attribute. Input types can be `text`, `checkbox`, `email`, `radio`, and more.
-`<input>`: The form element that is widely used to structure the form fields. It depends significantly on the value of the `type` attribute. Input types can be `text`, `checkbox`, `email`, `radio`, and more.
-`<button>`: It represents a clickable button that's used to submit the form data.
-`<button>`: Represents a clickable button that's used to submit the form data.
### Form Validation
### Form Validation
...
@@ -55,11 +55,11 @@ Client-side validation is further categorized as:
...
@@ -55,11 +55,11 @@ Client-side validation is further categorized as:
### Built-in Form Validation Using `required`, `type`, `minLength`, `maxLength`
### Built-in Form Validation Using `required`, `type`, `minLength`, `maxLength`
-`required`: Specifies which fields must be filled before submitting the form.
-`required`: Specifies which fields must be filled before submitting the form.
-`type`: Tells whether the data should be a number, email id, text string, etc.
-`type`: Specifies the data's type (i.e a number, email address, string, etc).
-`minLength`: Decides the minimum length for the text data string.
-`minLength`: Specifies minimum length for the text data string.
-`maxLength`: Decides the maximum length for the text data string.
-`maxLength`: Specifies maximum length for the text data string.
The following example shows using these attributes:
So, a form using this attributes may look like:
```html
```html
<!-- HTML Form with Built-in Validation -->
<!-- HTML Form with Built-in Validation -->
...
@@ -85,7 +85,7 @@ With these validation checks in place, when a user tries to submit an empty fiel
...
@@ -85,7 +85,7 @@ With these validation checks in place, when a user tries to submit an empty fiel
### JavaScript-based Form Validation
### JavaScript-based Form Validation
Form Validation is important to ensure that a user has submitted appropriate data. JavaScript offers an additional level of validation along with HTML native form attributes on the client side. Developers generally prefer validating form data through JavaScript because its data processing is faster when compared to server-side validation.
Form Validation is important to ensure that a user has submitted the correct data, in a correct format. JavaScript offers an additional level of validation along with HTML native form attributes on the client side. Developers generally prefer validating form data through JavaScript because its data processing is faster when compared to server-side validation, however front-end validation may be less secure in some scenarios as a malicious user could always send malformed data to your server.
The following example shows using JavaScript to validate a form:
The following example shows using JavaScript to validate a form:
...
@@ -143,7 +143,7 @@ The below example shows using the `pattern` attribute on an `input` element:
...
@@ -143,7 +143,7 @@ The below example shows using the `pattern` attribute on an `input` element:
</form>
</form>
```
```
The password form field must only contain digits (0 to 9) and lowercase alphabets (a to z). No other characters (#,$,&, etc.) are allowed. The rule in RegEx is written as `[a-z]{1,15}`.
The password form field must only contain digits (0 to 9), lowercase alphabets (a to z) and it must be no more than 15 characters in length. No other characters (#,$,&, etc.) are allowed. The rule in RegEx is written as `[a-z0-9]{1,15}`.
Middleware enables you to use code over configuration. This gives you full flexibility in Next.js, because you can run code before a request is completed. Based on the user's incoming request, you can modify the response by rewriting, redirecting, adding headers, or even streaming HTML.
Middleware enables you to use code over configuration. This gives you full flexibility in Next.js, because you can run code before a request is completed. Based on the user's incoming request, you can modify the response by rewriting, redirecting, adding headers, or even streaming HTML.
## Usage
## Usage
...
@@ -50,7 +60,7 @@ export type Middleware = (
...
@@ -50,7 +60,7 @@ export type Middleware = (
The function can be a default export and as such, does **not** have to be named `middleware`. Though this is a convention. Also note that you only need to make the function `async` if you are running asynchronous code.
The function can be a default export and as such, does **not** have to be named `middleware`. Though this is a convention. Also note that you only need to make the function `async` if you are running asynchronous code.
**Note:** Edge Functions are currently in Beta. The API might change as we look to continually make improvements.
[Read the full Middleware API reference.](/docs/api-reference/next/server.md)
@@ -14,3 +14,5 @@ For each, you'll want to check if the file is meant to be a page.
...
@@ -14,3 +14,5 @@ For each, you'll want to check if the file is meant to be a page.
If the file is not meant to be a page, and instead, is a shared component or file, move the file to a different folder like `components` or `lib`.
If the file is not meant to be a page, and instead, is a shared component or file, move the file to a different folder like `components` or `lib`.
If the file is meant to be a page, double check you have an `export default` with the React Component instead of an `export`. If you're already using `export default`, make sure the returned value is a valid React Component.
If the file is meant to be a page, double check you have an `export default` with the React Component instead of an `export`. If you're already using `export default`, make sure the returned value is a valid React Component.
If you need to support a different file extension for a page component (such as `.mdx`) or would like to include non-page files in the `pages` directory, configure [Custom Page Extensions](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions) in the `next.config.js`.
@@ -33,7 +33,7 @@ Once you have access to [the environment variables you'll need](#step-3-set-up-e
...
@@ -33,7 +33,7 @@ Once you have access to [the environment variables you'll need](#step-3-set-up-e
## How to use
## How to use
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:
Execute [`create-next-app`](https://github.com/vercel/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:
Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/zeit/next.js/discussions).
Your blog should be up and running on [http://localhost:3000](http://localhost:3000)! If it doesn't work, post on [GitHub discussions](https://github.com/vercel/next.js/discussions).
it('should not stream to google pagerender bot',async()=>{
it('should not stream to google pagerender bot',async()=>{
constres=awaitfetchViaHTTP(
constres=awaitfetchViaHTTP(
context.appPort,
context.appPort,
'/ssr',
'/ssr',
{},
{},
{
{
headers:{
headers:{
'user-agent':
'user-agent':
'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36 Google-PageRenderer Google (+https://developers.google.com/+/web/snippet/)',
'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36 Google-PageRenderer Google (+https://developers.google.com/+/web/snippet/)',
},
},
}
}
)
)
expect(res.headers.get('etag')).toBeDefined()
expect(res.headers.get('etag')).toBeDefined()
})
})
})
})
})
})
}
functionrunTest(mode,name,fn){
functionrunTest(mode,name,fn){
constcontext={appDir}
constcontext={appDir}
...
@@ -200,6 +223,9 @@ function runTest(mode, name, fn) {
...
@@ -200,6 +223,9 @@ function runTest(mode, name, fn) {