- Notifications
You must be signed in to change notification settings - Fork0
A minimalistic framework for universal server-rendered React applications
License
JavaScriptExpert/next.js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Next.js is a minimalistic framework for server-rendered React applications.
Install it:
$ npm install next --saveAfter 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:
importReactfrom'react'exportdefault()=>(<div>Welcome to next.js!</div>)
and then just runnext and go tohttp://localhost:3000
So far, we get:
- Automatic transpilation and bundling (with webpack and babel)
- Hot code reloading
- Server rendering and indexing of
./pages - Static file serving.
./static/is mapped to/static/
Everyimport you declare gets bundled and served with each page
importReactfrom'react'importcowsayfrom'cowsay-browser'exportdefault()=>(<pre>{cowsay({text:'hi there!'})}</pre>)
That means pages never load unneccessary code!
We useglamor to provide a great built-in solution for CSS isolation and modularization without trading off any CSS features
importReactfrom'react'importcssfrom'next/css'exportdefault()=>(<divclassName={style}> Hello world</div>)conststyle=css({background:'red',':hover':{background:'gray'},'@media (max-width: 600px)':{background:'blue'}})
We expose a built-in component for appending elements to the<head> of the page.
importReactfrom'react'importHeadfrom'next/head'exportdefault()=>(<div><Head><title>My page title</title><metaname="viewport"content="initial-scale=1.0, width=device-width"/></Head><p>Hello world!</p></div>)
When you need state, lifecycle hooks orinitial data population you can export aReact.Component:
importReactfrom'react'exportdefaultclassextendsReact.Component{staticasyncgetInitialProps({ req}){returnreq ?{userAgent:req.headers.userAgent} :{userAgent:navigator.userAgent}}render(){return<div> Hello World{this.props.userAgent}</div>}}
Client-side transitions between routes are enabled via a<Link> component
importReactfrom'react'importLinkfrom'next/link'exportdefault()=>(<div>Click<Linkhref="/about"><a>here</a></Link> to read more</div>)
importReactfrom'react'exportdefault()=>(<p>Welcome to About!</p>)
Client-side routing behaves exactly like the native UA:
- The component is fetched
- If it defines
getInitialProps, data is fetched. If an error occurs,_error.jsis rendered - After 1 and 2 complete,
pushStateis performed and the new component rendered
Each top-level component receives aurl property with the following API:
path-Stringof the current path excluding the query stringquery-Objectwith the parsed query string. Defaults to{}push(url)- performs apushStatecall associated with the current componentreplace(url)- performs areplaceStatecall associated with the current componentpushTo(url)- performs apushStatecall that renders the newurl. This is equivalent to following a<Link>replaceTo(url)- performs areplaceStatecall that renders the newurl
404 or 500 errors are handled both client and server side by a default componenterror.js. If you wish to override it, define a_error.js:
importReactfrom'react'exportdefaultclassErrorextendsReact.Component{staticgetInitialProps({ res, xhr}){conststatusCode=res ?res.statusCode :xhr.statusreturn{ statusCode}}render(){return(<p>An error{this.props.statusCode} occurred</p>)}}
To deploy, instead of runningnext, you probably want to build ahead of time. Therefore, building and starting are separate commands:
next buildnext start
For example, to deploy withnow apackage.json like follows is recommended:
{"name":"my-app","dependencies": {"next":"latest" },"scripts": {"dev":"next","build":"next build","start":"next start" }}Then runnow and enjoy!
Note: we recommend putting.next in.npmignore or.gitigore. Otherwise, usefiles ornow.files to opt-into a whitelist of files you want to deploy (and obviously exclude.next)
Is this production ready?
Next.js has been powering `https://zeit.co` since its inception.We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
How big is it?
The client side next bundle, which includes React and Glamor is73kb gzipped.
The Next runtime (lazy loading, routing,<Head>) contributes around15% to the size of that bundle.
The codebase is ~1500LOC (excluding CLI programs).
Is this like `create-react-app`?
Yes and No.
Yes in that both make your life easier.
No in that it enforces astructure so that we can do more advanced things like:
- Server side rendering
- Automatic code splitting
In addition, Next.js provides two built-in features that are critical for every single website:
- Routing with lazy component loading:
<Link>(by importingnext/link) - A way for components to alter
<head>:<Head>(by importingnext/head)
If you want to create re-usable React components that you can embed in your Next.js app or other React applications, usingcreate-react-app is a great idea. You can laterimport it and keep your codebase clean!
Why CSS-in-JS?
next/css is powered byGlamor. While it exposes a JavaScript API, it produces regular CSS and therefore important features like:hover, animations, media queries all work.
There’sno tradeoff in power. Instead, we gain the power of simpler composition and usage of JavaScript expressions.
Compiling regular CSS files would be counter-productive to some of our goals. Some of these are listed below.
Please note: we are very interested in supporting regular CSS, since it's so much easier to write and already familiar. To that end, we're currently exploring the possibility of leveraging Shadow DOM to avoid the entire CSS parsing and mangling step [#22]
Parsing, prefixing, modularizing and hot-code-reloading CSS can be avoided by just using JavaScript.
This results in better compilation performance and less memory usage, specially for large projects. Nocssom,postcss,cssnext or transformation plugins.
It also means fewer dependencies and fewer things for Next to do. Everything is Just JavaScript® (since JSX is completely optional)
Since every class name is invoked with thecss() helper, Next.js can intelligently add or remove<style> elements that are not being used.
This is important for server-side rendering, but also during the lifecycle of the page. Since Next.js enablespushState transitions that load components dynamically, unnecessary<style> elements would bring down performance over time.
This is a very signifcant benefit over approaches likerequire(‘xxxxx.css').
Since the class names and styles are defined as JavaScript objects, a variety of aids for correctness are much more easily enabled:
- Linting
- Type checking
- Autocompletion
While these are tractable for CSS itself, we don’t need to duplicate the efforts in tooling and libraries to accomplish them.
What syntactic features are transpiled? How do I change them?
We track V8. Since V8 has wide support for ES6 andasync andawait, we transpile those. Since V8 doesn’t support class decorators, we don’t transpile those.
See [this](link to default babel config we use) and [this](link to issue that tracks the ability to change babel options)
Why a new Router?
Next.js is special in that:
- Routes don’t need to be known ahead of time
- Routes are always be lazy-loadable
- Top-level components can define
getInitialPropsthat shouldblock 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:
- Every top level component receives a
urlobject to inspect the url or perform modifications to the history - A
<Link />component is used to wrap elements like anchors (<a/>) to perform client-side transitions
We tested the flexibility of the routing with some interesting scenarios. For an example, check outnextgram.
How do I define a custom fancy route?
We’re adding the ability to map between an arbitrary URL and any component by supplying a request handler:#25
On the client side, we'll add a parameter to<Link> so that itdecorates the URL differently from the URL itfetches.
How do I fetch data?
It’s up to you.getInitialProps is anasync function (or a regular function that returns aPromise). It can retrieve data from anywhere.
Can I use it with Redux?
Yes! Here's anexample
Why does it load the runtime from a CDN by default?
We intend for Next.js to be a great starting point for any website or app, no matter how small.
If you’re building a very small mostly-content website, you still want to benefit from features like lazy-loading, a component architecture and module bundling.
But in some cases, the size of React itself would far exceed the content of the page!
For this reason we want to promote a situation where users can share the cache for the basic runtime across internet properties. The application code continues to load from your server as usual.
We are committed to providing a great uptime and levels of security for our CDN. Even so, we alsoautomatically fall back if the CDN script fails to loadwith a simple trick.
To turn the CDN off, just set{ “next”: { “cdn”: false } } inpackage.json.
What is this inspired by?
Many of the goals we set out to accomplish were the ones listed inThe 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 acomponent 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 acrossreact-page (now deprecated), a similar approach to Next.js by the creator of React Jordan Walke.
The following issues are currently being explored and input from the community is appreciated:
- Support for pluggable renderers [#20]
- Style isolation through Shadow DOM or "full css support" [#22]
- Better JSX [#22]
- Custom server logic and routing [#25]
- Custom babel config [#26]
- Custom webpack config [#40]
- Naoyuki Kanezawa (@nkzawa) – ▲ZEIT
- Tony Kovanen (@rase-) – ▲ZEIT
- Guillermo Rauch (@rauchg) – ▲ZEIT
- Dan Zajdband (@impronunciable) – Knight-Mozilla / Coral Project
About
A minimalistic framework for universal server-rendered React applications
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Languages
- JavaScript100.0%