app template

template repository for next.js apps.

how to run

prerequisites:

• node.js v22
• pnpm v10

[!TIP]

you can use pnpm to install the required node.js version with pnpm env use 22 --global

set required environment variables in .env.local:

bash cp .env.local.example .env.local

also, set environment variables required by validation and deployment github actions. use "variables" for every environment variable prefixed with NEXT_PUBLIC_, and "secrets" for all others.

the default template accepts the following variables:

• NEXT_PUBLIC_REDMINE_ID (required): service issue for this application in the acdh redmine issue tracker.
• NEXT_PUBLIC_APP_BASE_URL (required): the base url for this application. the default of "http://localhost:3000" should be fine for local development.
• NEXT_PUBLIC_IMPRINT_SERVICE_BASE_URL (required): the base url for the acdh imprint service, which uses NEXT_PUBLIC_REDMINE_ID to fetch the imprint text.
• NEXT_PUBLIC_BOTS (required): whether this website can be indexed by web crawlers like the google bot. supported values are "disabled" and "enabled", defaults to "disabled".
• NEXT_PUBLIC_MATOMO_BASE_URL and NEXT_PUBLIC_MATOMO_ID (optional): set these to support client-side analytics with matomo.
• NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION (optional): set this to verify site ownership for google search console.
• ENV_VALIDATION (optional): whether to validate environment variables. supported values are "disabled", "enabled", and "public". defaults to "enabled". "public" only validates build-args prefixed with NEXT_PUBLIC_, which can make sense in a docker build context.

when adding new environment variables, don't forget to add them to .env.local.example and config/env.config.ts as well.

install dependencies:

bash pnpm install

run a development server on http://localhost:3000:

bash pnpm run dev

[!TIP]

this template supports developing in containers. when opening the project in your editor, you should be prompted to re-open it in a devcontainer.

how to test

generate a production build and run end-to-end tests with:

bash pnpm run build pnpm run test:e2e

visual snapshot tests should be run in the template's devcontainer - or a comparable debian bookworm based linux environment -, and can be updated with:

bash pnpm run test:e2e:update-snapshots

how to deploy

• ask a sysadmin to create a new acdh kubernetes project.
• create a new namespace in that project via rancher, and set the KUBE_NAMESPACE github variable to that namespace
• adjust the app_name, which will be the name of the deployment in the above namespace.
• set the PUBLIC_URL github variable to the application's public url (e.g. "https://my-app.acdh-dev.oeaw.ac.at"), and set the KUBE_INGRESS_BASE_DOMAIN to the public url's base domain (e.g. "acdh-dev.oeaw.ac.at"). PUBLIC_URL should match NEXT_PUBLIC_APP_BASE_URL.
• when deploying to a production domain (i.e. a domain not ending in "acdh-dev.oeaw.ac.at"), set HELM_UPGRADE_EXTRA_ARGS to --set 'ingress.annotations.cert-manager\.io/cluster-issuer=acdh-prod' for "acdh.oeaw.ac.at" domains, or to --set 'ingress.annotations.cert-manager\.io/cluster-issuer=letsencrypt-prod' for any other non-oeaw domains, and ensure KUBE_INGRESS_BASE_DOMAIN is set correctly.
• if you haven't yet, create a service issue in the acdh redmine issue tracker, and set the SERVICE_ID github variable to the issue number. this should match the NEXT_PUBLIC_REDMINE_ID variable in your .env.local file.
• ensure required build args (prefixed with NEXT_PUBLIC_) are referenced in both the Dockerfile, as well as the validation and deployment pipelines, and set as github variables.
• ensure required runtime environment variables are referenced in the validation and deployment pipelines, and set as github secrets. github secrets need to be prefixed with K8S_SECRET_ to be automatically copied to the runtime environment. in case you need secrets in the docker build context, you can mount a secret in the Dockerfile.
• ensure both the github repository, as well as the package registry is set to public.
• the NEXT_PUBLIC_BOTS variable defaults to "disabled", which signals to web crawlers that the website should not be indexed. when deploying to a production domain (i.e. a domain not ending in "acdh-dev.oeaw.ac.at") this should be set to "enabled".

if everything is set up correctly, every git push to the main branch will create a new deployment if the validation pipeline passes.

you can reference the template repository for a working setup.

production deployment checklist

• [ ] update PUBLIC_URL, KUBE_INGRESS_BASE_DOMAIN, HELM_UPGRADE_EXTRA_ARGS github variables.
• [ ] get a matomo id for the app, and set both NEXT_PUBLIC_MATOMO_BASE_URL and NEXT_PUBLIC_MATOMO_ID.
• [ ] set NEXT_PUBLIC_BOTS to "enabled".
• [ ] ensure app/sitemap.ts generates entries for dynamic pages.
• [ ] optionally, create a google search console property, and provide the verification token as NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION. once verfied, submit sitemap.xml in the search console settings.
• [ ] when using the variant/with-rss-feed branch, ensure app/[locale]/rss.xml/route.ts generates feed entries.

template variants

• variant/with-auth branch: adds email and password authentication with database sessions, including email verification, password reset, and two-factor auth. uses drizzle as orm.

• variant/with-commitlint branch: enables commitlint and runs it as a git hook, and as part of the validation workflow in a github action.

• variant/with-email branch: adds nodemailer for sending emails, and an example contact form.

• variant/with-keystatic branch: adds keystatic for content management. allows editing .mdx and .json files, and pushes changes to github.

• variant/with-opentelemetry branch: adds instrumentation to collect tracing information and send it to an opentelementry collector.

• variant/with-rss-feed branch: adds an rss feed.

• variant/with-sentry branch: enables error reporting with sentry.

• variant/with-single-locale branch: adjusts the template to support a single pre-configured locale only, and removes internationalised routing. ui strings are still managed in the messages folder to make it easy to activate full i18n support later if needed.

• variant/with-storybook branch: adds storybook for building ui components in isolation and creating component documentation.

• variant/with-unit-tests branch: adds vitest for unit testing.