AppName

October 13, 2025 ยท View on GitHub

Production Staging Development Megalinter CI Checks Within Web Performance Budget

App responsible for all appname related data.

Setting up your repository

Upon cloning, fill in the values for the .env.example and save this as a new .env in the root directory. Run the following:

Getting Started

git clone https://github.com/abarrows/template-nextjs-ui

Prerequisites

You will need:

  • An OS package manager
  • NVM & Node
    • Install the same Node version listed in the .nvmrc file
  • NPM
    • Comes with Node installation
  • Docker
    • MacOS: brew cask install docker
    • Windows: choco install docker-desktop
  • Powershell
    • MacOS: brew install --cask powershell
    • Windows: choco install powershell-core

Building the Project

To start the app locally:

  1. Retrieve the .env file by running one of the commands in the Retrieving Environment Variables section
  2. From the root project directory, run
    • npm run dev to start a development server with hot reloading
    • npm run build && npm start to build and start a production server without hot reloading
    • docker compose up --build to build and start the application using Docker
  3. Open app in browser: http://localhost:3000

Environment Variables

The environment variables for this project were previously sourced from Azure Key Vault Secrets. WIP: I will create a branch soon to update this process so that it sources from either AWS Secret Manager. Until then, simply replace the values with you personal situation's values..

Retrieving Environment Variables

You have options when generating a local .env file:

  • To generate a .env file for a specific environment: In a PowerShell session, run ./Get-Secrets.ps1 -Environment [ENVIRONMENT]. If no environment is provided, the script defaults to the "development" environment.
  • To generate a .env file for a specific key vault: In a PowerShell session, run ./Get-Secrets.ps1 -KeyVaultName [KEY VAULT NAME]. You can find the available key vaults for this project below.
  • To generate a .env file for a specific environment: In a shell session, run npm run setup [ENVIRONMENT] (also runs npm install). If no environment is provided, the script defaults to the "development" environment.

Here are the available Azure Key Vault names for this project:

  • template-ui-development
  • template-ui-staging
  • template-ui-production

Using Environment Variables

These files are where you can find and manage environment variables:

  • Secrets-example.json - sample variables for each Key Vault
  • Secrets.json - secrets config file for each Key Vault
    • Generate and edit with npm run keys:edit or ./Edit-Secrets.ps1
    • Save and apply changes with npm run keys:save or ./Set-Secrets.ps1
  • .env - variables for the selected Key Vault
    • Generated by npm run setup and npm run keys:get
  • .env.development - override non-secret values from .env while developing the project locally
  • .env.production - override non-secret values from .env while building the project locally
  • .env*.local - override secret values for local use only
    • This file is optional and should only be used for advanced configuration

Onboarding A New UI Product

  1. Review .env.example,
  2. TODO: ONBOARDING: Review all instances of this and follow the TODO instructions for the new product.
  3. Once all is finished, run the npm run validate or the npm run validate:ci command which executes all setup scripts, tests, linting, etc. to ensure that everything works correctly without errors:
npm run validate
  1. USER Update with the repo's owner name.
  2. USER_EMAIL Update with the repo's owner email.

Development Essentials

Hooks

Our ESLint config is set up to validate hooks, including useEffect dependency arrays. Before disabling a warning because you believe something doesn't belong in deps, read through A Complete Guide to useEffect and try to find another solution. It's OK to disable a linter if you have good reason (leave a comment explaining why if that reason isn't immediately obvious), but that particular rule should never be disabled.

State Management

We use hooks for local state and React Context for wider (but non-global) state. For global state we use Zustand.

Styling

We use SCSS Modules to style components. SCSS Modules are CSS Modules, but with all the power of SCSS (nesting, variables, etc). SCSS Modules scope styles to just that component, as opposed to making them globally available. Our entrypoint for global styles is in `src/styles/index.scss.

BEM

BEM is our preferred naming convention, which is slightly modified for convenience. This allows us to more easily access classes within JSX, like styles.blockName instead of styles['block-name'].

// Original BEM
.block-name
.block-name--modifier-name
.block-name__element-name
.block-name__element-name--modifier-name

// ACB BEM, uses camelCase and replaces -- with _
.blockName
.blockName_modifierName
.blockName__elementName
.blockName__elementName_modifierName

Testing

Test files should be stored in the same location as the original file they are testing, with the exception of Playwright tests (see below).

We run tests automatically with GitHub Actions on every Pull Request, failing tests will need to be addressed before a PR can be merged.

Jest & React Testing Library

We use Jest for helper function tests. For more information about working with Jest, this is a useful guide.

We use React Testing Library for component tests that simulate how a user would interact with the component. There are several available queries for selecting the element you need to test.

Debugging Tools:

  • The screen object allows us to interact with the component we have rendered and find elements. Screen provides a debug method that will print the document or specified elements.
  • Screen provides another method called logTestingPlaygroundURL. This method will print a url in your terminal for you to copy and paste in your browser where you can further test the entire document or an element.

Run unit tests with npm run test:unit.

Playwright

We use Playwright as our end-to-end testing framework. All Playwright tests are contained in playwright/integration directory as .spec.js files.

Debugging Tools:

Run integration tests with npm run test:e2e.

Storybook

We use Storybook for component documentation and style guides. It can be run locally with npm run storybook:dev.

Deployments & Releases tom did you move this stuff bud

We use GitHub Actions to deploy this project. More information on how to deploy using GitHub Actions here: [GitHub Action Deployments](TODO: ONBOARDING:github-action-deployments-url)

Onboarding A New UI Product

  1. APPLICATION_NAME Find and replace all references of this with the real product's name.
  2. TODO: ONBOARDING: Review all instances of this and follow the TODO instructions for the new product.
  3. Once all is finished, run the preflight command which executes all setup scripts, tests, linting, etc. to ensure that everything works correctly without errors:
npm run validate