Ample's NEXT.js starter configured with Prismic Slice Machine

This starter serves as the starting point for Ample NEXT.js development projects that use Prismic's Slice Machine. It has pre-configured preferences to make getting started less cumbersome. To create a new project from this template, click the green "Use this Template" button above.

Ample's Next.js starter can be found here.

Prerequisite

Install VOLTA

curl https://get.volta.sh | bash && volta install node && volta install yarn@1

Getting started

cd next-prismic-slice-machine-starter-ample

Install node packages

yarn

Start the development server (http://localhost:3000)

yarn develop

Storybook and Chromatic

Storybook is used for documentation, development, and visual testing.

Start the storybook server (http://localhost:6006)

yarn storybook

Chromatic is used for gathering UI feedback, visual testing, and publishing Storybook.

Storybook stories are pushed to Chromatic with Github actions in each PR.

To push to Chromatic locally, use the following command:

yarn chromatic

Testing

Percy is used for visual testing, Jest for Unit Testing, and Storyshots for automating Jest Snapshots on Storybook Stories.

Percy Visual testing (with Cypress)

Percy tests run pre-push, and visual snapshots can be reviewed on the project's dashboard at percy.io.

To test Percy locally, open Cypress and pick a browser:

yarn cypress:open

Jest

yarn test

To update failing snapshots, run the following command

yarn test:update

Documentation

Alias Imports

This project supports alias imports. This provides a means for importing components without needing to know exactly where you are in the tree. It can make moving items around a little less painful.

The convention is to treat directories in our project like NPM scopes. The scope is to prepend with a @ character. There are several prefixes supported out of the box:

@components maps to ./components
@layout maps to ./layout
@root maps to ./
@slices maps to ./slices
@templates maps to ./templates
@utilities maps to ./utilities

Aliases need to be configured in NEXT.js, Storybook, Jest, and VS Code for seamless integration across the board. Therefore, they are replicated (with the appropriate syntax) in:

.config/.jest/jest.config.js
.config/.storybook/main.js
jsconfig.json

Linters

It's recommended to set up seamless integration with your editor.

ESLint statically analyzes your code to find problems in JavaScript quickly. (editor-integration)
Prettier enforces a code formatting style guide for consistency across the team. (editor-integration)
Stylelint helps avoid errors and enforces conventions in styles. (editor-integration)

Note: For an optimal development experience in VS Code install recommended workspace extensions. When using VS Code, most ESLint and Stylelint conventions will be fixed automatically.

Linters run pre-commit on staged files to ensure there are no errors or warnings.

Additional documentation for this project can be found in Storybook.

Environment variables

direnv is used to load and unload environment variables.

Create a .envrc file in the root directory and add the following project environment variables.

export CHROMATIC_PROJECT_TOKEN="chromatic-project-token-goes-here"
export NEXT_PUBLIC_SITE_URL="http://localhost:3000"
export PERCY_TOKEN="percy-token-goes-here"

License

next-starter-ample is distributed under the MIT License.

ample / next-prismic-slice-machine-starter

readme