This is the allaboutapps TypeScript template for React NextJS applications.
This template requires a Node version of 20. If you are using nvm, then run nvm use to use the correct version. If 20 is not installed run nvm install.
- run
npm_config_yes=true npx tiged github:allaboutapps/next-starter my-project-nameto scaffold a new app, wheremy-project-nameis the name of the target folder where you want to create your project. - change the "name" to your project name in
package.json. - run
git initif you want to initialize a repository. (The template comes with a pre commit hook that lints the project before a commit. A repository is needed for the commit hook to install correctly.) - run
yarn && yarn devto install packages and start the dev server - You can start editing the page by modifying
app/page.tsx. The page auto-updates as you edit the file.
For headless CraftCMS projects there is a separate branch. Use npm_config_yes=true npx tiged github:allaboutapps/next-starter#craft my-project-name for scaffolding. ATTENTION: this is mainly provided for allaboutapps internal use
- We strive to support Visual Studio Code as much as possible.
- Automatically installs compatible versions of popular libraries within our organization.
- Support for compile-time safe i18n through customized typings and utils in the projects.
- Sample Login-Page in the frontend code.
- Docker setup
For developing, previewing and testing UI components we highly recommend using storybook. Support
for storybook is built in. For examples how to write simple stories see *.stories.tsx files (e.g. src/components/ui/Buttons.stories.tsx).
To start the storybook use yarn storybook.
- Builds are configured as
standalonein next.config.mjs. SPA style builds (akaoutput: "export") are not practical, since dynamic routes withoutgenerateStaticParams()are not supported (see https://nextjs.org/docs/app/building-your-application/deploying/static-exports#unsupported-features). This limitation would not allow any detail sites likeproduct/[productId]because those cannot be generated statically. - Local production builds can be tested using
yarn build:localandyarn start:local - Support for aaa build pipeline using woodpecker CI is provided in .drone.yml
- Dockerfile ist provided and can be tested locally using
yarn docker:buildandyarn docker:run. The app is then reachable under http://localhost:3000
- We don't use
NEXT_PUBLIC_env vars on client side, because those are baked at build time. Since we only want to build a single docker image we use a different approach by using server side env vars for configuration (currently onlyRUNTIME_ENVIRONMENT) and forwarding them to our client components. Use the globalpublicEnvVarsvariable to access the env vars on the client side. RUNTIME_ENVIRONMENT
- Configure build variants in
hostSettings.ts. Put in public configs like api base urls directly. Secrets that are only used in react server components or API endpoints should not be exposed and MUST be set via environment variables (do NOT forward those to the client usingpublicEnvVars).
- When the project is built in woodpecker CI, the commit hash will automatically be inserted into the
<head>as comment.
When you have many strings in your application it can be hard for QA and translators to figure out which string key in your language file (e.g. en.ts) is used for which on screen text.
For this you can open your browser console (CMD+ALT+i in Mac Chrome or CTRL+SHIFT+i in Windows Chrome), enter debugShowStringKeys(true) and then press RETURN. This will display the string keys additionally to the translated text. Toggle this off again by using debugShowStringKeys(false).
You can add additional debug commands later in useDebugCommands.ts. To list all available debug commands use debugHelp() in the browser console.
Icons are located and defined in src/component/ui/Icon.tsx.
To add new ones following steps are necessary:
- Copy SVG content
- Add content to path, set filename (Replace with a if you want to set transformations for all child elements)
- Camel case the attributes inside the SVG
All assets are put into /public/assets. No files should be put into /public/ root. This is because of localization middleware
prepending locales automatically (see vercel/next.js#36308)
You could additionally have an asset folder per language which gives you the ability to localize assets as well. See vercel/next.js#36308 (comment).
You can generate a file containing used third party licenses using yarn license-check. CC-BY-4.0 is included because of NextJS including caniuse-lite which is using CC-BY-4.0. So the license file is mandatory for attribution.
yarn build will automatically generate a license file.
Projects built using this template assume being served at domain root. E.g. my-project.com/. If you want to
serve in a subfolder like my-domain.com/my-project then you have to configure the basePath variable in
next.config.mjs.
Some caveats: You might need to consider some changes with e.g. linked images, also i18n related redirects in middleware.ts might have to be adapted.
Currently this template does not support changing the base path at runtime. Build time base path changes are supported
by NextJS directly in next.config.mjs using the basePath variable which is consumed at build time. So you'd need
a separate build for each base path. See discussion here vercel/next.js#41769.
Should you absolutely need a runtime configurable base path in your project then consider this approach (works with Next 14, but could break in future versions). vercel/next.js#41769 (reply in thread)
Unit tests via vitest are supported. Run them via yarn test locally and yarn test:ci in your CI environment.
We provide a script that lets you generate TypeScript types for a Swagger specification.
Run yarn codegen local <file_name> to generate types from a swagger file in your local repository. Note that the file needs to be located at the root folder.
To use a remote source run yarn codegen dev. Don't forget to set a correct BASE_URL in swagger-codegen.sh which can be found in ./scripts.
Favicon can be set using src/app/favicon.ico bigger versions can be set using src/app/icon.png. Should your
application need more versions, follow the documentation at https://nextjs.org/docs/app/api-reference/file-conventions/metadata/app-icons
For social media link images you can use this: https://nextjs.org/docs/app/api-reference/file-conventions/metadata/app-icons
E.g. robots.txt, sitemap, manifest: See https://nextjs.org/docs/app/api-reference/file-conventions/metadata