Next.js 9.3 – Static Site Support, 32 KB Smaller Runtime

We are excited today to introduce Next.js 9.3, featuring:

• Next-gen Static Site Generation (SSG) Support : Built-in optimized static generation through new data fetching methods.
• : Bypass statically generated pages to display drafts from a CMS.
• Built-In Sass Support for Global Stylesheets : Applications can now directly import .scss files as global stylesheets.
• Built-In Sass CSS Module Support for Component-Level Styles : Leveraging the .module.scss convention, locally scoped CSS can be imported and used anywhere in your application.
• Automatic Static Optimization for 404 : Improved speed and reliability by serving the 404 page statically.
• 32 kB Smaller Runtime : Smaller runtime size for all Next.js applications through powerful optimizations.
• Next.js Community on GitHub Discussions : You can now discuss and ask questions right from the Next.js repository on GitHub.

All of these benefits are non-breaking and fully backwards compatible. All you need to do to update is run:

npm i next@latest react@latest react-dom@latest

When building websites or web applications you generally have to choose between 2 strategies: Static generation ( SSG ) or server-side rendering ( SSR ).

Next.js is the first hybrid framework, allowing you to choose the technique that fits your use case best on a per-page basis.

Next.js 9.0 introduced the concept of Automatic Static Optimization . When a page does not have blocking data fetching requirements like getInitialProps , it will be automatically rendered to HTML at build time.

There are more cases where you might want to render a page to static HTML at build time, even with blocking data fetching requirements. An example of this is marketing pages powered by a (headless) Content Management System ( CMS ) or a blog section of the site.

We've collaborated with heavy users of SSG and next export like HashiCorp and extensively discussed the right constraints with the community in the most commented on RFC in the history of Next.js to create a new unified way to do data fetching and static generation.

Today we're incredibly excited to announce two new data fetching methods: getStaticProps and getServerSideProps . We also include a way to provide parameters to statically generate static pages for dynamic routes: getStaticPaths .

These new methods have many advantages over the getInitialProps model as there is a clear distinction between what will become SSG vs SSR.

• getStaticProps (Static Generation): Fetch data at  build-time .

• getStaticPaths (Static Generation): Specify dynamic routesto prerender based on data.

• getServerSideProps (Server-Side Rendering): Fetch data on  each request .

• These improvements are API additions. All new functionality is completely backwards compatible and can be incrementally adopted. No deprecations are introduced and getInitialProps will continue to function as it currently does. We do encourage adopting these new methods on new pages and projects.

If you export an async function called  getStaticProps from a page, Next.js will pre-render this page at build time. This is especially useful when you want to render specific static pages from a CMS.

getStaticProps always runs in the Node.js context and the code is automatically tree-shaken from browser bundles, ensuring that less code is sent to the browser. This way you don't have to worry about the execution of data fetching code in both Node.js and browser environments, which have some inconsistencies.

This allows you to use any asynchronous or even synchronous data fetching technique, including fetch , REST, GraphQL, or even directly accessing a database.

export async function getStaticProps(context) {
  return {
    props: {} // will be passed to the page component as props
  }
}

The context parameter is an object containing the following keys:

• params :  params  contains the route parameters for pages using dynamic routes. For example, if the page name is  [id].js  , then  params  will look like  { id: ... } . To learn more, take a look at the  Dynamic Routing documentation . You should use this together with  getStaticPaths , which we’ll explain later.

Here’s an example which uses getStaticProps to fetch a list of blog posts from a CMS:

// You can use any data fetching library
import fetch from 'node-fetch'

// posts will be populated at build time by getStaticProps()
function Blog({ posts }) {
  return (
    <ul>
      {posts.map(post => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// This function gets called at build time in the Node.js environment.
// It won't be called on client-side, so you can even do
// direct database queries. See the "Technical details" section.
export async function getStaticProps() {
  // Call an external API endpoint to get posts.
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // By returning { props: posts }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts
    }
  }
}

export default Blog

You should use getStaticProps if:

getStaticProps

To learn more about getStaticProps refer to the Data Fetching Documentation .

If a page hasdynamic routes and uses  getStaticProps it needs to define a list of paths that have to be rendered to HTML at build time.

If you export an async function called  getStaticPaths from a page that uses dynamic routes, Next.js will statically pre-render all the paths specified by  getStaticPaths .

export async function getStaticPaths() {
  return {
    paths: [
      { params: { ... } } // See the "paths" section below
    ],
    fallback: true or false // See the "fallback" section below
  };
}

The paths key determines which paths will be pre-rendered. For example, suppose that you have a page that uses dynamic routes named pages/posts/[id].js . If you export getStaticPaths from this page and return the following for paths:

return {
  paths: [
    { params: { id: 1 } },
    { params: { id: 2 } }
  ],
  fallback: ...
}

Then Next.js will statically generate posts/1 and  posts/2 at build time using the page component in  pages/posts/[id].js .

Note that the value for each params must match the parameters used in the page name:

• If the page name is  pages/posts/[postId]/[commentId] , then  params  should contain  postId  and  commentId .
• If the page name uses catch-all routes, for example,  pages/[...slug] , then  params  should contain  slug  which is an array. For example, if this array is  ['foo', 'bar'] , then Next.js will statically generate the page at  /foo/bar .

The object returned by getStaticPaths must contain a boolean fallback key.

If fallback is  false , then any paths not returned by  getStaticPaths will result in a  404 page . This is useful if you know that all paths will be known at build time.

Here’s an example which pre-renders one blog post per page called pages/posts/[id].js . The list of blog posts will be fetched from a CMS and returned by  getStaticPaths . Then, for each page, it fetches the post data from a CMS using  getStaticProps .

// pages/posts/[id].js
import fetch from 'node-fetch'

function Post({ post }) {
  // Render post...
}

// This function gets called at build time
export async function getStaticPaths() {
  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Get the paths we want to pre-render based on posts
  const paths = posts.map(post => `/posts/${post.id}`)

  // We'll pre-render only these paths at build time.
  // { fallback: false } means other routes should 404.
  return { paths, fallback: false }
}

// This also gets called at build time
export async function getStaticProps({ params }) {
  // params contains the post `id`.
  // If the route is like /posts/1, then params.id is 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // Pass post data to the page via props
  return { props: { post } }
}

export default Post

If fallback is  true , then the behavior of  getStaticProps changes, Next.js will render the provided paths to HTML at build time. When a path was not generated at build time it will be generated on-demand when a user requests the page.

This is useful when your application has many routes that can be statically generated but you don't want to incur increased build times for pages by only generating a subset at build time.

The user that triggers the generation of the page will be served a fallback HTML, this is generally a page with a loading state. The reason for this is that static HTML can be served from a CDN, ensuring that the page is always fast, even when it hasn't been generated yet.

An example of on-demand statically generating additional pages:

// pages/posts/[id].js
import { useRouter } from 'next/router'
import fetch from 'node-fetch'

function Post({ post }) {
  const router = useRouter()

  // If the page is not yet generated, this will be displayed
  // initially until getStaticProps() finishes running
  if (router.isFallback) {
    return <div>Loading...</div>
  }

  // Render post...
}

// This function gets called at build time
export async function getStaticPaths() {
  return {
    // Only `/posts/1` and `/posts/2` are generated at build time
    paths: [{ params: { id: 1 } }, { params: { id: 2 } }],
    // Enable statically generating additional pages
    // For example: `/posts/3`
    fallback: true
  }
}

// This also gets called at build time
export async function getStaticProps({ params }) {
  // params contains the post `id`.
  // If the route is like /posts/1, then params.id is 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // Pass post data to the page via props
  return { props: { post } }
}

export default Post

To learn more about getStaticPaths refer to the Data Fetching Documentation .

If you export an async function called  getServerSideProps from a page, Next.js will render this page on each request (SSR).

getServerSideProps always runs server-side and the code is automatically tree-shaken from browser bundles, ensuring that less code is sent to the browser. This way you don't have to worry about the execution of data fetching code in both server and browser environments, which have some inconsistencies. This increases performance in many cases as the server will generally have a faster connection to the data source. It also increases security by exposing less of the data fetching logic.

This allows you to use any asynchronous or even synchronous data fetching technique, including fetch , REST, GraphQL, or even directly accessing a database.

When navigating between pages using next/link instead of executing getServerSideProps in the browser Next.js will do a fetch to the server which will return the result of calling getServerSideProps .

export async function getServerSideProps(context) {
  return {
    props: {} // will be passed to the page component as props
  }
}

The context parameter is an object containing the following keys:

• params : If this page uses a dynamic route,  params  contains the route parameters. If the page name is  [id].js  , then  params  will look like  { id: ... } . To learn more, take a look at the  Dynamic Routing documentation .
• req :  The HTTP request object .
• res :  The HTTP response object .
• query : The query string.

Here’s an example which uses getServerSideProps to fetch data at request time and renders it:

function Page({ data }) {
  // Render data...
}

// This gets called on every request
export async function getServerSideProps() {
  // Fetch data from external API
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  // Pass data to the page via props
  return { props: { data } }
}

export default Page

To learn more about getServerSideProps refer to the Data Fetching Documentation .

As discussed earlier in this post, Static Generation is useful when your pages fetch data from a headless CMS. However, it’s not ideal when you’re writing a draft on your headless CMS and want to preview the draft immediately on your page. As the output is static previewing changes becomes harder as you'd have to regenerate that static page.

The introduction of getStaticProps in Next.js opens up new possibilities like leveraging Next.js' on-demand rendering capabilities under certain conditions.

For example, when previewing a draft from your headless CMS you'd want bypass the static rendering and on-demand render the page with the draft content instead of the published content. You’d want Next.js to bypass Static Generation only for this specific case.

We are happy to announce a new built-in feature of Next.js to address this need: Preview Mode.

Preview Mode allows users to bypass the statically generated page to on-demand render (SSR) a draft page from for example a CMS.

However, you're not just limited to certain CMS systems. Preview Mode integrates directly with both getStaticProps and getServerSideProps so it can be used with any type of data fetching solution.

Preview Mode is already available when using next start , or seamlessly by deploying to theZEIT Now CDN.

Try it out preview mode yourself on https://next-preview.now.sh/

Learn more aboutPreview Mode by referencingthe documentation.

getStaticProps allows you to fetch data from any data source, including CMS systems

We're actively collaborating with many of the key players in the CMS ecosystem to provide examples and guides on integrating with Next.js.

Examples which are currently being actively worked on include:

• Agility CMS
• Craft CMS
• Crystallize
• DatoCMS
• Elliot
• TinaCMS
• Prismic
• Sanity
• Storyblok
• Strapi
• TakeShape

If your company is active in the CMS ecosystem, we'd love to work with you! Feel free to reach out on email or Twitter .

Next.js 9.2 introduced built-in support for Global CSS Stylesheets to replace the next-css plugin with better defaults to provide a more optimized result.

Right after the release we increasingly got asked to integrate Sass support as many businesses moving to Next.js have an existing design system based on Sass.

Upon investigating Next.js plugin usage we found that approximately 30% of Next.js applications use next-sass today. Compared to 44% using vanilla CSS and 6% using Less.

Furthermore, next-sass had the same missing constraints as next-css . Meaning that you could import a Sass file in every file of the project, however, this imported Sass file would be global for the whole application.

After considering these statistics and feedback we're delighted to announce that Next.js now has built-in support for importing Sass stylesheets.

To get started using CSS imports in your application, import the CSS file within pages/_app.js .

For example, consider the following stylesheet named styles.scss in the root of your project:

$primary-color: #333;

body {
  padding: 20px 20px 60px;
  margin: 0;
  color: $primary-color;
}

Create a pages/_app.js file if not already present. Then, import the styles.scss file:

import '../styles.scss'

// This default export is required in a new `pages/_app.js` file.
export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

Since stylesheets are global by nature, they must be imported in the Custom <App> component . This is necessary to avoid class name and ordering conflicts for global styles.

In development, expressing stylesheets this way allows your styles to be automatically updated on the page as you edit them.

In production, all Sass and CSS files will be automatically concatenated into a single minified .css file. This CSS file will be loaded via a <link> tag and automatically injected into the default HTML markup Next.js generates.

This new feature is fully backwards compatible. If you are using @zeit/next-sass or other CSS related plugins the feature is disabled to avoid conflicts.

If you are currently using @zeit/next-sass we recommend removing the plugin from your next.config.js and package.json , thereby moving to the built-in Sass support upon upgrading.

Next.js now supports CSS Modules with Sass files using the  [name].module.scss file naming convention.

Unlike the support previously available in Next.js 5+ using next-sass , global Sass and CSS modules can now  coexist —  next-sass required all  .scss files in your application be handled as global or local, but not both.

CSS Modules locally scope Sass by automatically creating unique class names. This allows you to use the same Sass class name in different files without worrying about collisions.

This behavior makes CSS Modules the ideal way to include component-level Sass. CSS Module files can be imported anywhere in your application .

For example, consider a reusable Button component in the  components/ folder:

First, create components/Button.module.scss with the following content:

/*
You do not need to worry about .error {} colliding with any other `.css` or
`.module.css` files!
*/
$color: white;

.error {
  color: $color;
  background-color: red;
}

Then, create components/Button.js , importing and using the above CSS file:

import styles from './Button.module.scss'

export function Button() {
  return (
    <button
      type="button"
      // Note how the "error" class is accessed as a property on the imported
      // `styles` object.
      className={styles.error}
    >
      Destroy
    </button>
  )
}

CSS Modules for Sass files are an optional feature and are only enabled for files with the  .module.scss extension. Regular  <link>  stylesheets and global Sass stylesare still supported.

In production, all CSS Module files are automatically concatenated into many minified and code-split  .css  files . These  .css files represent hot execution paths in your application, ensuring the minimal amount of CSS is loaded per-page for your application to paint.

Like above, this new feature is fully backwards compatible. If you are using @zeit/next-sass or other CSS related plugins the feature is disabled to avoid conflicts.

If you are currently using @zeit/next-sass we recommend removing the plugin from your  next.config.js and  package.json , thereby moving to the built-in Sass support.

The release of Next.js 9 introduced the concept of Automatic Static Optimization when a page does not have blocking data requirements Next.js will automatically generate the page as static HTML at build-time. However, there was one page that wasn't automatically rendered as static HTML: the 404 page. The main reason that the 404 page wasn't made static automatically was that the /_error page powering 404 was handling more than just 404, for example, errors.

Given that the 404 pages get rendered for non-existent routes rendering the page on-demand could cause increased cost and server load.

We set out to put you in the pit of success in 2 ways:

• The default Next.js experience generates a static 404 page
• When customizing the 404 page it still makes sure you end up with a static page

This feature is fully backwards compatible so if you currently have a custom pages/_error.js it will continue to be used for the 404 page until you add pages/404.js .

When your application doesn't have a custom pages/_error.js page Next.js will automatically statically generate the 404 page and use that when a 404 has to be served. This happens automatically and no changes are needed.

To override the default 404 page you can now create a pages/404.js which will still be automatically statically optimized at build time. This page is used instead of pages/_error.js to render a 404 if your application has one.

// pages/404.js
export default () => <h1>This is the 404 page</h1>

Next.js supports the same browsers as React itself , with no required configuration. This includes Internet Explorer 11 (IE11) and all popular browsers (Edge, Firefox, Chrome, Safari, Opera, et al).

As part of this compatibility, we also compile your application to be IE11 compatible: this allows you to safely use ES6 + syntax features, Async/Await, Object Rest/Spread Properties, and more—all with zero configuration necessary.

Part of this compilation process also involves transparently injecting the necessary feature polyfills (e.g. Array.from or Symbol ). However, these polyfills are only necessary for less than 10% of web traffic , in most cases to support IE11.

Starting in Next.js 9.3, Next.js will automatically load the polyfills needed to support legacy browsers, and only loads the polyfills in these legacy browsers.

In practice, this means 32 kB or more will be eliminated from your First Load size for 90%+ of your users .

These size savings are even greater for larger applications that rely on even more browser features.

This optimization is fully automatic and no application changes are necessary to take advantage of it!

We're very excited to see the continued growth in Next.js adoption:

• We have had over  927  independent contributors.
• On GitHub, the project has been starred over  46,600  times.
• The  examples directory  has over  226 examples.

The Next.js community now has over 15,250 members. The community can now be found on GitHub discussions, a new place for the community to discuss and ask questions!  Join us!

We are thankful to our community and all the external feedback and contributions that helped shape this release.

Special thanks to Jeff Escalante for significant feedback on the new data fetching methods.

Huge thanks to everyone who contributed to this release: @arcanis, @lgordey, @ijjk, @martpie, @jaywink, @fabianishere, @dijs, @TheRusskiy, @quinnturner, @timneutkens, @lfades, @vvo, @adithwip, @rafaelalmeidatk, @bmathews, @Spy-Seth, @EvgeniyKumachev, @chibicode, @piglovesyou, @HaNdTriX, @Timer, @janicklas-ralph, @devknoll, @prateekbh, @ethanryan, @MoOx, @rifaidev, @msweeneydev, @motiko, and @balazsorban44 for helping!