We use TypeScript extensively, and try to enable it wherever possible (sources, Jest, Cypress, Storybook...)
Code architecture and build
All your code should go into the
/src directory (doc).
This folder structure is officially supported by Next. It is relevant when you have a lot of development tooling alongside your actual codebase, like we do in Vulcan.
src folder has its own
tsconfig.json: this way collocated files like Stories and Unit tests are correctly handled by your text editor, but they can be excluded from the root
tsconfig.json to avoid bloating Next.js build.
The structure of a plugin system of Next is still under discussion. In the meantime, we strive to provide code as clean as possible, structured in package, so you can easily remove prebundled features.
To do so, we currently use a Webpack config so folders in
packages/@vulcanjs can be imported the same way as
node_modules. For instance,
packages/@vulcanjs/next-utils can be imported as
import "@vulcanjs/next-utils" in your code.
You can reproduce the same behaviour with any other prefix by changing
However, you are not forced to structure your own code as packages. Avoid Hasty Abstractions!
Magic src imports with
Import code in
src from anywhere by writing
Relative imports are a huge mess to support. A relative import should never go further than the category it belongs too:
pages should never have to import
components using a messy
Scripts written in TypeScript
We have created a command
yarn run build:scripts that builds files from
.vn/scripts/ts-sources into reusable
.js scripts. You can reuse
your code utilities within those scripts. The build script is based on Vercel ncc builder.
We allow folders and packages to contain an
index.server file, that will be used at build time depending on the environment.
/!\ You still need to have a bare
index file alongside those environment specific file. Otherwise TypeScript will complain (see the "Learnings" documentation for more details).
Env variables in .env
We demo Next.js 9.4 new feature,
.env file support. Open
.env.development to see the default development variables.
Transition from Vulcan Meteor
If you were using Vulcan Meteor, check
https://github.com/VulcanJS/vulcan-meteor-next-transition for a demonstration of using Vulcan Next for the frontend
and an existing Vulcan Meteor app for the backend.
Passing package.json info to the client app
next.config.js, you'll find a demonstration of how to safely inject informations from your
package.json into your Next application.
For example, we use it to inject current version into the
html tag for better deployment tracking.
Sitemap.xml and Robots.txt with next-sitemap
DEBUG=vns:perf npm run dev
yarn auto-changelog to compute a new changelog. Works best in combination with
yarn version (to create git version tags automatically) and
git merge --no-ff your-feature (to get merge commits).
Design system best practices
Based on Emma Bostian's course on Frontend Masters, we include basic examples and libraries to get you started writing a design system for your UI. This means:
- An example of a styled button, with Material UI and Styled Components
- A modal example
- Animations with react-spring
- A powerful Storybook configuration
src/components/ui for the code, and run Storybook to see the demos.
No more excuses to make dull UIs, you have all the tools you need :)
i18n without custom server
IMPORTANT NOTE: there is one last blocking issue with serverless deployment on Vercel. To put it in a nutshell prevents your locale JSON to be deployed alongside your pages.
More broadly, it is related to the impossibility of reading static files in Next when deployed to Vercel at the moment.
Lang in the custom _document
lang attribute is set automatically on
<html> during server-render
Get started by reading MDXJS official doc. If you want to write a blog with fancy interactive blocks, you'll fall in love with this feature.
Thanks to next-mdx-remote, you can easily use markdown files as your CMS.
/docs page when running the app to see the live documentation.
MD and MDX import in React
Loading MD/MDX in Storybook
Work out of the box. Will however disable default behaviour for ".md" import of Storybook, which is replaced by MDX behaviour.
Webpack bundle analyzer
yarn run analyze-bundle to get insight on your Webpack build.
Dockerfile for production
Dockerfile for Cypress
Running Cypress in Docker makes it easier to run your tests locally, while you keep coding. You can also use this file for your CI/CD process.
3rd party tooling as optional dependencies
As a default, Jest, Cypress, Storybook and any other 3rd party tooling is installed as optional dependencies.
- "dependencies" is what your app need to run
- "devDependencies" is what your app need to be built
- "optionalDependencies" is everything else
Package.json naming convention are not intuitive and do not allow for a clean, environment-based distinction between packages. So that's the best we could do!