Tim-W-James/react-ts-template

Opinionated template for frontend React TypeScript projects with Vite, ESLint, Prettier, Vitetest, and more. Includes a README template

React TS Template

Opinionated template for frontend React TypeScript projects with Vite, ESLint, Prettier, Vitetest, and more packages. This template aims to speed up the initial configuration and boilerplate for new projects, while providing integration with a range of modern tooling. This repo also includes a React starter app using Bootstrap Components and React Router 6.

Template includes:

• : frontend framework
• : frontend build tool and dev server, configured in ./vite.config.ts
• : types for js. Configured in ./tsconfig.json
• : CSS preprocessor
• : Linter/code analyzer for TypeScript. Configured in ./.eslintrc.cjs with rules from AirBnB and SonarJS
• : Linter/code analyzer for SCSS. Configured in ./.stylelintrc.cjs
• : Formatter. Configured in ./.prettierrc.cjs
• : unit testing framework. Configured in ./vite.config.ts > test
• : view, document and test individual components and pages. Configured in ./.storybook/main.cjs
• : global imports. Configured in ./vite.config.ts > Plugins > AutoImport
• : configuration for the pnpm package manager for better performance, lockfiles and monorepo support. See steps below if you wish to use a different package manager.
• scripts - run with pnpm run <script>:
  • dev - starts a dev environment on localhost with Hot Module Reloading (automatically updates when source code changes)
  • dev:https - starts a dev environment on localhost over https (requires local development certificates to be generated, or use vite-plugin-basic-ssl to auto generate certs)
  • build - compile production source code to ./dist
  • preview - after build, preview on localhost
  • lint - evaluate ESLint rules against source code
  • format - format source code with prettier and try to fix any ESLint errors
  • test:run - run tests using Vitest
  • test:ui - run tests and display a UI on localhost
  • test - run unit tests in watch mode (automatically reruns tests when source code changes)
  • coverage - run coverage tests and output results to ./coverage
  • storybook - launch Storybook to view, document and test components and pages
• : pre-commit Git hooks to lint, format and run tests. Configured in ./.husky
• : GitHub bot for automatic dependency updates. Configured in ./renovate.json
• : GitHub CI/CD pipeline. Configured in ./.github/workflows
• Starter React app with and
• See the Project Structure

Complete the configuration checklist below and remove from the README once complete.

TODO

• If using VSCode, install recommended extensions with the command pallet: Extensions:Show Recommended Extensions. Otherwise, use install anEditorConfig plugin for your text editor or IDE of choice
• Specify the following fields with a search and replace: repo_name, project_title, project_description, project_keywords
• Replace personal information with your own: Tim-W-James, Tim James, tim.jameswork9800@gmail.com, https://linkedin.com/in/timothy-william-james/, https://timjames.dev
• Specify the LICENSE.txt for the project and set ./package.json > license
• README.md - there is a README template below based on the Best-README-Template. Find a list of resources to help you write READMEs in a comment at the end of this file. Fill out the following:
  • Fill out each section of the README as needed, uncommenting/removing sections as needed.
  • Add images for the following: ./public/assets/images/logo.png, ./public/assets/images/screenshot.png
• Set the target ES version (ES6 - supported by most browsers, ESNext - latest):
  • ./.eslint.cjs:
    • "<target>": true
    • "ecmaVersion": <target>
  • ./tsconfig.json:
    • "target": "<target>"
    • "module": "<target>"
    • "lib": ["<target>", "DOM"]
  • Append --target <target> to the build script in ./package.json or specify the target in ./vite.config.ts > build > target
• Specify formatting and editor configuration in ./.editorconfig. Use the ./.prettierrc.cjs for js specific rules that are not defined in ./.editorconfig
• Add any global imports to ./vite.config.ts > Plugins > AutoImport. You may also need to update the Vite configuration used in ./.storybook/main.cjs
• Specify node version in the ./.nvmrc and ./package.json > engines > node
• This repo is configured for the pnpm package manager. If you wish to change this to yarn or npm, configure the following:
  • Modify ./package.json > engines and ./package.json > packageManager to refer to the version of the package manager you are using
  • Modify the GitHub actions in ./.github/workflows to install your package manager (if using something other than npm), use it in pipeline steps, and cache
  • Modify any scripts that call pnpm in ./package.json > scripts
  • Modify any Git hooks that call pnpm in ./.husky/pre-commit
  • Update the README instructions accordingly
  • Remove the old lockfile and regenerate it if needed:
    • pnpm: pnpm i --lockfile-only
    • yarn: yarn install --mode update-lockfile
    • npm: npm install --package-lock-only
  • NOT RECOMMENDED: If you don't want to commit your lockfile, add it to the ./.gitignore and change the GitHub Action step "Install Dependencies" (for npm, change npm ci to npm i).
• Install dependencies with your package manager of choice:
  • pnpm: pnpm i
  • yarn: yarn
  • npm: npm ci (lockfile) or npm i (no lockfile)
• Install Git hooks if needed (this should happen automatically when dependencies are installed): husky install
• Add continuous deployment workflow to ./.github/workflows as needed
• Install the Renovate bot on GitHub for automatic dependency updates
• Finally, remove/modify the sample code:
  • ./src/example-component.tsx and ./src/example-component.test.tsx (example for using Vitest and snapshots)
  • ./src/stories (example Storybook)
  • ./public/assets
  • Anything else you don't need in ./src
  • And any dependencies you don't need such as react-bootstrap or react-icons

↑ Remove everything above once setup is complete. ↑

project_title

project_description

Table of Contents

1. About The Project
   • Goals
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Development
   • Testing
   • Code Style
   • Project Structure
   • Documentation

About The Project

About text.

Goals

• Stuff to do

Getting Started

Prerequisites

• Install node for the version in .nvmrc or use nvm:

  nvm install && nvm use

• Install the pnpm package manager. Use corepack for automatic installation, which is an experimental node feature that must be enabled using:

  corepack enable

Installation

• Clone the repo:

  git clone https://github.com/Tim-W-James/repo_name.git

• Install dependencies with pnpm:

  pnpm i

Usage

• Build to ./dist and preview:

  pnpm build
  pnpm preview

Development

• Ensure you have Git Hooks enabled (should run automatically after pnpm i):

  npx husky install

• Start a development environment:

  pnpm dev

Testing

• Run unit tests in watch mode (automatically reruns tests when source code changes):

  pnpm test

• Run coverage tests and output results to ./coverage:

  pnpm coverage

• View and test individual components or pages:

  pnpm storybook

Code Style

• Evaluate ESLint (./.eslintrc.cjs) and StyleLint (./.stylelintrc.cjs) rules against source code:

  pnpm lint

• Format source code with prettier (./.prettierrc.cjs) and try to fix any ESLint (./.eslintrc.cjs) or StyleLint (./.stylelintrc.cjs) errors:

  pnpm format

Project Structure

• Source Code: ./src
  • Entry point and routes: ./src/index.tsx
  • Root component: ./src/App.tsx
  • Common components: ./src/components. Has alias @components. Group by type for layout, buttons, forms, etc.
  • Common hooks: ./src/hooks. Has alias @hooks
  • Common utils: ./src/utils. Has alias @utils
  • Pages: ./src/pages. Has alias @pages. Nest subfolders for components, utils, hooks, etc. depending on the scope they apply to
  • React context: ./src/context. Has alias @context
• Unit Tests: place tests adjacent to source code
• Storybook Stories: place stories adjacent to source code
• SCSS Styling:
  • Use index.scss for globals
  • Place page or component specific styles adjacent to source code, using scoped .modules
• Global TypeScript Types: ./types
• Web Accessible Files (robots.txt, manifest.json, etc.): ./public
• Site Assets (favicon.svg, images, etc.): ./public/assets. Has alias @assets

Define path alias in ./tsconfig.paths.json.

I recommend using VSCode file nesting for a cleaner file tree.

Documentation

• Document code with JSDoc

• Document components or pages with Storybook and run with:

  pnpm storybook

↑ Back to Top ↑