You can click on the button Use this template or start a new project with create-next-app
npx create-next-app -e https://github.com/jmlweb/tsnextstarter #or yarn create next-app -e https://github.com/jmlweb/tsnextstarter #or pnpm create next-app -e https://github.com/jmlweb/tsnextstarter
- To be opinionated on the tools, but not on the code
- To help implementing a scalable, module-based directory organization
- The basic Next.js template with TypeScript support
- Jest and Testing Library (provided by @swc/jest for better performance)
- Mocking for http req and res (useful for API handlers)
- Two layouts are ready to be used: A “common” one (intended to be used as default) and an “empty” one (just in case you need a completely different look & feel for some pages)
- Storybook configured and integrated with Next.js
- Cypress is already configured for Next.js and integrated with GitHub actions
- conventional commits integration:
- runs linting for code and commit message on each commit
- GitHub actions:
- testing & building
- package.json & tag version bumping (based on semantic commits)
What’s not included?
- Any styling solution
- Any library for state management, nor for graphql/rest handling
- Visual changes to the standard create-next-app template
dev: Start server on dev mode
build: Build code for production
start: Start production server
lint: Lint code
test: Run Jest
test:watch: Run Jest on watch mode for the file provided as argument
test:watchAll: Run Jest on watch mode for all the files
test:coverage: Run Jest on coverage mode
prepare: Install husky hooks
commit: Run commitizen
release: Run changelog generation and version bumping
storybook: Run Storybook in development mode
build-storybook: Run Storybook in build mode
? Directories organization
For a better organization, the code is organized inside the
src folder, while the configuration files and the
public directory are located at the root level.
This folder is used only for routing purposes. Every file inside the
pages folder should not have any logic attached but to re-export the modules (default for the Component, named for server-side data fetching functions) from the
scene represents a logical set of screens (or just one) from the application and is formed by:
- One or more “page” components.
- If they are needed, one or more data-fetching functions (
- Other files or folders which are used by the scene(s) component(s).
scene can serve to different
pages, by using different combinations of
page components and
scenecould export two different components (or “sub-scenes”), along with the same
- The two components represent the same information and use internally most of the same sub-components while maintaining a completely different layout (including subtle variations on the sub-components).
- The route “/items/layout-a” could point to one of the components, while “/items/layout-b” could point to the other one.
If needed, a
scene can contain also other folders like
data… with modules shared across the scene.
If you want, you can place your unit tests and stories at the same level as your code.
Each subfolder inside the
apiHandlers folder contains one or more handlers (which will be later imported by the api routes) and optionally the tests, utilities, or any other type of auxiliary file.
The layout is formed by a component, along with a function called
getLayout which will be imported by the scene and placed in the special
getLayout property of the scene component.
src/components, src/data, src/helpers, src/utils…
Just use a folder at the
src level for any kind of file which is shared by two or more
You can use this directory for your integration tests with Jest
e2e (and/or integration) tests and fixtures for Cypress
Configuration files for Storybook
CI/CD and bumping workflows for GitHub Actions
Shall I use the version bumping manually or with the action provided
If you are using already GitHub actions
- If are comfortable with the workflow, just remember not to run the
- If you prefer to bump manually, delete the
.github/workflowsfolder. Whenever you want to do the bumping, run the
releasescript and push your files and tags.
If you are not using GitHub actions
You can safely delete the
.github folder or just forget about its existence as it won’t harm your project.
How to integrate X feature/technology into my project?
Please, refer to the official Next.js documentation