![Introducing Dashboard Analytics](https://cdn.sanity.io/images/cgdhsj6q/production/af327c5bd94708db501516a75da6870aef894c64-2286x1522.png?w=400&fit=max&auto=format)
Product
Introducing Dashboard Analytics
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.
The 'next' npm package is a popular framework for building server-side rendered and statically generated React applications. It provides a set of features that simplify the development of modern web applications, including page-based routing, pre-rendering, automatic code splitting, and API routes.
Page-based routing
Next.js provides a file-system-based router built on the concept of pages. When a file is added to the pages directory, it's automatically available as a route.
export default function Home() {
return <div>Welcome to Next.js!</div>
}
API Routes
Next.js allows you to create API endpoints as part of your Next.js application. These are server-side functions that you can deploy alongside your application.
export default function handler(req, res) {
res.status(200).json({ message: 'Hello from Next.js!' })
}
Static Generation and Server-Side Rendering
Next.js supports two forms of pre-rendering: Static Generation and Server-Side Rendering. This feature allows you to generate HTML in advance for optimal performance.
export async function getStaticProps() {
const data = await fetchData();
return { props: { data } };
}
Built-in CSS and Sass Support
Next.js allows you to import CSS and Sass files directly within your JavaScript components, providing a streamlined development experience.
import '../styles/globals.css';
export default function App({ Component, pageProps }) {
return <Component {...pageProps} />
}
Automatic Code Splitting
Next.js automatically splits your code into small bundles that are loaded as needed, improving load times and performance.
import dynamic from 'next/dynamic';
const DynamicComponent = dynamic(() => import('../components/hello'));
export default function Home() {
return <DynamicComponent />
}
Gatsby is a React-based static site generator that provides similar functionalities to Next.js, such as pre-rendering and code splitting. However, Gatsby is more focused on static site generation, whereas Next.js offers a hybrid approach with both static generation and server-side rendering.
Nuxt.js is a framework based on Vue.js that offers functionalities similar to Next.js but for Vue.js applications. It provides server-side rendering, static site generation, and automatic code splitting, much like Next.js does for React applications.
Create React App is a boilerplate to create single-page React applications. It sets up a development environment and builds scripts but does not offer server-side rendering or static site generation out of the box like Next.js does.
Sapper is a framework for building web applications using Svelte, offering server-side rendering and static site generation. It's similar to Next.js in terms of goals but is designed for Svelte instead of React.
Next.js is a minimalistic framework for server-rendered React applications.
**NOTE! the README on the master
branch might not match that of the latest stable release! **
Install it:
npm install next --save
and add a script to your package.json like this:
{
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
}
}
After that, the file-system is the main API. Every .js
file becomes a route that gets automatically processed and rendered.
Populate ./pages/index.js
inside your project:
export default () => (
<div>Welcome to next.js!</div>
)
and then just run npm run dev
and go to http://localhost:3000
So far, we get:
./pages
./static/
is mapped to /static/
To see how simple this is, check out the sample app - nextgram
Every import
you declare gets bundled and served with each page. That means pages never load unnecessary code!
import cowsay from 'cowsay-browser'
export default () => (
<pre>{ cowsay.say({ text: 'hi there!' }) }</pre>
)
We bundle styled-jsx to provide support for isolated scoped CSS. The aim is to support "shadow CSS" resembling of Web Components, which unfortunately do not support server-rendering and are JS-only.
export default () => (
<div>
Hello world
<p>scoped!</p>
<style jsx>{`
p {
color: blue;
}
div {
background: red;
}
@media (max-width: 600px) {
div {
background: blue;
}
}
`}</style>
</div>
)
It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:
export default () => (
<p style={{ color: 'red' }}>hi there</p>
)
To use more sophisticated CSS-in-JS solutions, you typically have to implement style flushing for server-side rendering. We enable this by allowing you to define your own custom <Document>
component that wraps each page
Create a folder called static
in your project root directory. From your code you can then reference those files with /static/
URLs:
export default () => (
<img src="/static/my-image.png" />
)
<head>
We expose a built-in component for appending elements to the <head>
of the page.
import Head from 'next/head'
export default () => (
<div>
<Head>
<title>My page title</title>
<meta name="viewport" content="initial-scale=1.0, width=device-width" />
</Head>
<p>Hello world!</p>
</div>
)
Note: The contents of <head>
get cleared upon unmounting the component, so make sure each page completely defines what it needs in <head>
, without making assumptions about what other pages added
When you need state, lifecycle hooks or initial data population you can export a React.Component
(instead of a stateless function, like shown above):
import React from 'react'
export default class extends React.Component {
static async getInitialProps ({ req }) {
return req
? { userAgent: req.headers['user-agent'] }
: { userAgent: navigator.userAgent }
}
render () {
return <div>
Hello World {this.props.userAgent}
</div>
}
}
Notice that to load data when the page loads, we use getInitialProps
which is an async
static method. It can asynchronously fetch anything that resolves to a JavaScript plain Object
, which populates props
.
For the initial page load, getInitialProps
will execute on the server only. getInitialProps
will only be executed on the client when navigating to a different route via the Link
component or using the routing APIs.
getInitialProps
receives a context object with the following properties:
pathname
- path section of URLquery
- query string section of URL parsed as an objectreq
- HTTP request object (server only)res
- HTTP response object (server only)xhr
- XMLHttpRequest object (client only)err
- Error object if any error is encountered during the rendering<Link>
Client-side transitions between routes can be enabled via a <Link>
component. Consider these two pages:
// pages/index.js
import Link from 'next/link'
export default () => (
<div>Click <Link href="/about"><a>here</a></Link> to read more</div>
)
// pages/about.js
export default () => (
<p>Welcome to About!</p>
)
Note: use next/prefetch
for maximum performance, to link and prefetch at the same time in the background
Client-side routing behaves exactly like the browser:
getInitialProps
, data is fetched. If an error occurs, _error.js
is renderedpushState
is performed and the new component renderedEach top-level component receives a url
property with the following API:
pathname
- String
of the current path excluding the query stringquery
- Object
with the parsed query string. Defaults to {}
push(url, as=url)
- performs a pushState
call with the given urlreplace(url, as=url)
- performs a replaceState
call with the given urlThe second as
parameter for push
and replace
is an optional decoration of the URL. Useful if you configured custom routes on the server.
You can also do client-side page transitions using the next/router
import Router from 'next/router'
export default () => (
<div>Click <span onClick={() => Router.push('/about')}>here</span> to read more</div>
)
Above Router
object comes with the following API:
route
- String
of the current routepathname
- String
of the current path excluding the query stringquery
- Object
with the parsed query string. Defaults to {}
push(url, as=url)
- performs a pushState
call with the given urlreplace(url, as=url)
- performs a replaceState
call with the given urlThe second as
parameter for push
and replace
is an optional decoration of the URL. Useful if you configured custom routes on the server.
Note: in order to programmatically change the route without triggering navigation and component-fetching, use props.url.push
and props.url.replace
within a component
You can also listen to different events happening inside the Router. Here's a list of supported events:
routeChangeStart(url)
- Fires when a route starts to changerouteChangeComplete(url)
- Fires when a route changed completelyrouteChangeError(err, url)
- Fires when there's an error when changing routesHere
url
is the URL shown in the browser. If you callRouter.push(url, as)
(or similar), then the value ofurl
will beas
.
Here's how to properly listen to the router event routeChangeStart
:
Router.onRouteChangeStart = (url) => {
console.log('App is changing to: ', url)
}
If you are no longer want to listen to that event, you can simply unset the event listener like this:
Router.onRouteChangeStart = null
If a route load is cancelled (for example by clicking two links rapidly in succession), routeChangeError
will fire. The passed err
will contained a cancelled
property set to true
.
Router.onRouteChangeError = (err, url) => {
if (err.cancelled) {
console.log(`Route to ${url} was cancelled!`)
}
}
Next.js exposes a module that configures a ServiceWorker
automatically to prefetch pages: next/prefetch
.
Since Next.js server-renders your pages, this allows all the future interaction paths of your app to be instant. Effectively Next.js gives you the great initial download performance of a website, with the ahead-of-time download capabilities of an app. Read more.
<Link>
You can substitute your usage of <Link>
with the default export of next/prefetch
. For example:
import Link from 'next/prefetch'
// example header component
export default () => (
<nav>
<ul>
<li><Link href='/'><a>Home</a></Link></li>
<li><Link href='/about'><a>About</a></Link></li>
<li><Link href='/contact'><a>Contact</a></Link></li>
</ul>
</nav>
)
When this higher-level <Link>
component is first used, the ServiceWorker
gets installed. To turn off prefetching on a per-<Link>
basis, you can use the prefetch
attribute:
<Link href='/contact' prefetch={false}><a>Home</a></Link>
Most needs are addressed by <Link />
, but we also expose an imperative API for advanced usage:
import { prefetch } from 'next/prefetch'
export default ({ url }) => (
<div>
<a onClick={ () => setTimeout(() => url.pushTo('/dynamic'), 100) }>
A route transition will happen after 100ms
</a>
{
// but we can prefetch it!
prefetch('/dynamic')
}
</div>
)
Typically you start your next server with next start
. It's possible, however, to start a server 100% programmatically in order to customize routes, use route patterns, etc
This example makes /a
resolve to ./pages/b
, and /b
resolve to ./pages/a
:
const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()
app.prepare().then(() => {
createServer((req, res) => {
const parsedUrl = parse(req.url, true)
const { pathname, query } = parsedUrl
if (pathname === '/a') {
app.render(req, res, '/b', query)
} else if (pathname === '/b') {
app.render(req, res, '/a', query)
} else {
handle(req, res, parsedUrl)
}
})
.listen(3000, (err) => {
if (err) throw err
console.log('> Ready on http://localhost:3000')
})
})
The next
API is as follows:
next(path: string, opts: object)
- path
isnext(opts: object)
Supported options:
dev
(bool
) whether to launch Next.js in dev mode - default false
dir
(string
) where the Next project is located - default '.'
quiet
(bool
) Display error messages with server information - default false
<Document>
Pages in Next.js
skip the definition of the surrounding document's markup. For example, you never include <html>
, <body>
, etc. To override that default behavior, you must create a file at ./pages/_document.js
, where you can extend the Document
class:
// ./pages/_document.js
import Document, { Head, Main, NextScript } from 'next/document'
export default class MyDocument extends Document {
static async getInitialProps (ctx) {
const props = await Document.getInitialProps(ctx)
return { ...props, customValue: 'hi there!' }
}
render () {
return (
<html>
<Head>
<style>{`body { margin: 0 } /* custom! */`}</style>
</Head>
<body className="custom_class">
{this.props.customValue}
<Main />
<NextScript />
</body>
</html>
)
}
}
The ctx
object is equivalent to the one received in all getInitialProps
hooks, with one addition:
renderPage
(Function
) a callback that executes the actual React rendering logic (synchronously). It's useful to decorate this function in order to support server-rendering wrappers like Aphrodite's renderStatic
404 or 500 errors are handled both client and server side by a default component error.js
. If you wish to override it, define a _error.js
:
import React from 'react'
export default class Error extends React.Component {
static getInitialProps ({ res, xhr }) {
const statusCode = res ? res.statusCode : (xhr ? xhr.status : null)
return { statusCode }
}
render () {
return (
<p>{
this.props.statusCode
? `An error ${this.props.statusCode} occurred on server`
: 'An error occurred on client'
}</p>
)
}
}
For custom advanced behavior of Next.js, you can create a next.config.js
in the root of your project directory (next to pages/
and package.json
).
Note: next.config.js
is a regular Node.js module, not a JSON file. It gets used by the Next server and build phases, and not included in the browser build.
// next.config.js
module.exports = {
/* config options here */
}
In order to extend our usage of webpack
, you can define a function that extends its config via next.config.js
.
// This file is not going through babel transformation.
// So, we write it in vanilla JS
// (But you could use ES2015 features supported by your Node.js version)
module.exports = {
webpack: (config, { dev }) => {
// Perform customizations to config
// Important: return the modified config
return config
}
}
Warning: Adding loaders to support new file types (css, less, svg, etc.) is not recommended because only the client code gets bundled via webpack and thus it won't work on the initial server rendering. Babel plugins are a good alternative because they're applied consistently between server/client rendering (e.g. babel-plugin-inline-react-svg).
In order to extend our usage of babel
, you can simply define a .babelrc
file at the root of your app. This file is optional.
If found, we're going to consider it the source of truth, therefore it needs to define what next needs as well, which is the next/babel
preset.
This is designed so that you are not surprised by modifications we could make to the babel configurations.
Here's an example .babelrc
file:
{
"presets": [
"next/babel",
"stage-0"
],
}
To deploy, instead of running next
, you probably want to build ahead of time. Therefore, building and starting are separate commands:
next build
next start
For example, to deploy with now
a package.json
like follows is recommended:
{
"name": "my-app",
"dependencies": {
"next": "latest"
},
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
}
}
Then run now
and enjoy!
Note: we recommend putting .next
in .npmignore
or .gitignore
. Otherwise, use files
or now.files
to opt-into a whitelist of files you want to deploy (and obviously exclude .next
)
We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
The client side bundle size should be measured in a per-app basis. A small Next main bundle is around 65kb gzipped.
Yes and No.
Yes in that both make your life easier.
No in that it enforces a structure so that we can do more advanced things like:
In addition, Next.js provides two built-in features that are critical for every single website:
<Link>
(by importing next/link
)<head>
: <Head>
(by importing next/head
)If you want to create re-usable React components that you can embed in your Next.js app or other React applications, using create-react-app
is a great idea. You can later import
it and keep your codebase clean!
Next.js bundles styled-jsx supporting scoped css. However you can use a CSS-in-JS solution in your Next app by just including your favorite library as mentioned before in the document.
We track V8. Since V8 has wide support for ES6 and async
and await
, we transpile those. Since V8 doesn’t support class decorators, we don’t transpile those.
Next.js is special in that:
getInitialProps
that should block the loading of the route (either when server-rendering or lazy-loading)As a result, we were able to introduce a very simple approach to routing that consists of two pieces:
url
object to inspect the url or perform modifications to the history<Link />
component is used to wrap elements like anchors (<a/>
) to perform client-side transitionsWe tested the flexibility of the routing with some interesting scenarios. For an example, check out nextgram.
We added the ability to map between an arbitrary URL and any component by supplying a request handler.
On the client side, we have a parameter call as
on <Link>
that decorates the URL differently from the URL it fetches.
It’s up to you. getInitialProps
is an async
function (or a regular function that returns a Promise
). It can retrieve data from anywhere.
Yes! Here's an example with Apollo.
Yes! Here's an example
Many of the goals we set out to accomplish were the ones listed in The 7 principles of Rich Web Applications by Guillermo Rauch.
The ease-of-use of PHP is a great inspiration. We feel Next.js is a suitable replacement for many scenarios where you otherwise would use PHP to output HTML.
Unlike PHP, we benefit from the ES6 module system and every file exports a component or function that can be easily imported for lazy evaluation or testing.
As we were researching options for server-rendering React that didn’t involve a large number of steps, we came across react-page (now deprecated), a similar approach to Next.js by the creator of React Jordan Walke.
Our Roadmap towards 2.0.0 is public.
FAQs
The React Framework
The npm package next receives a total of 4,285,877 weekly downloads. As such, next popularity was classified as popular.
We found that next demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.
Security News
A new OpenSSF report uncovers critical gaps in secure software training, with 75% of new developers unfamiliar with secure practices, highlighting urgent educational needs.
Security News
The 2023 Python Developers Survey reveals key trends in packaging, web frameworks, and developer demographics, highlighting a shift toward innovative tools as the Python community diversifies and grows among less experienced developers.