Vite Boilerplate

This is a boilerplate setup for a Vite based React app.

It comes with all the tools and configuration you need to start developing right away, automatically preventing errors and adhering to conventions and best practices.

Tech Stack

App

The actual app only comes with a minimal setup, to cater to the individual needs of the project:

• React
• TypeScript (a path alias ~ is set up for './src', so you can import modules from the root as ~/components/..., ~/modules/..., etc.) (config)
• React Router: browser router
• TanStack Query (React Query): asynchronous state management
• i18next: internationalization (i18n) (config)
• tailwindcss: utility class based CSS framework (config)
• Google Fonts: free web fonts (Roboto; loaded in index.html)
• react-helmet: document head manager for React

Build / Dev Tools

• Browserslist: define supported browsers for frontend tools (config)
• Dev Container (config) w/ Docker (config) and Docker Compose (config)
• EditorConfig: configure IDE for consistent coding style (config)
• ESLint: find and fix problems in JavaScript code (config)
• Husky: git hooks for automatically linting code, running tests, etc. The hooks should be set up automatically on checkout via the prepare package script.
  • pre-commit hook for running lint-staged and checking types
  • pre-push hook for preventing directly pushing to the main branch
• i18next-scanner: scan code, extract translation keys/values, and merge them into i18n resource files (config)
• import-sort: sort JavaScript/TypeScript imports according to a config (similar to Python isort)
• lint-staged: run linters (and other packages scripts) on git staged files (config)
• Prettier: format code (config)
• polyfill.io: automatically deliver the polyfills required by the user's web browser (loaded in index.html)
• Stylelint: CSS linter to avoid errors and enforce conventions (config)
• Vite: super fast next generation frontend tooling (config)
• million: linter to identify and fix slow code plus compiler to automatically speed up React (config)
• VSCode settings: format on save, add missing imports, update imports on file move, etc. plus recommended VSCode extensions
• Webfont Download: Vite plugin to automatically download and bundle Google web fonts
• plugin-web-update-notification: Vite plugin to detect new releases and notify user to reload (config)

Testing

• Vitest for unit tests; files matching .test. are run with Vitest and the test package script (config)
• Playwright for end-to-end tests; files matching .spec. are run with Playwright and the test:e2e package script (config)
• Storybook for component tests (config)
• istanbul/nyc for code coverage reports

Folder Structure

• public: files publicly accessible through the browser
  • locales: translation files, organized by language
• src: application source code
  • assets: images, SVGs, etc.
  • components: UI components, organized according to Atomic Design principles
    • atoms: foundational building blocks w/o dependencies
    • molecules: groups of components including other components
    • organisms: pieces of functionality built from groups of components
    • templates: page-level objects that place components into a layout
  • constants: constant values
  • modules: self-contained pieces of functionality
  • stories: Storybook story definitions
  • styles: theme and styles
  • typings: TypeScript type definitions and modules
  • utils: reusable functions and libraries, e.g. for string manipulation, internationalization, working with arrays, etc.
• e2e-tests: end-to-end tests (unit tests are co-located with the corresponding files)

Installation

This repo provides a Dev Container to enable developing in a fully pre-set up and isolated environment.

Prerequisites: To use Dev Containers, you need to have Docker and the VSCode extension for Dev Containers set up.

When you open the project in VSCode, it will show a popup informing you that the "Folder contains a Dev Container". Click the "Reopen in container" button to start the container and open the folder in the container with VSCode configured and all recommended plugins installed. It will also install all required dependencies for you.

When you open the container for the first time, the container needs to build, which might take a little time. Once it has been built, starting the container is almost instant.

If you don't want to work with the Dev Container, you need to install the dependencies with yarn install after checking out the repo.

Usage

Starting the Devserver

Start the Vite devserver with

yarn dev

You can then open the application on http://localhost:5173 in your browser.

Building the App

Create a production build of the app with

yarn build

You can run the production build locally with

yarn preview

Package Scripts

Some package scripts are run automatically or as components of other package scripts.

The scripts you will typically use are

• dev: start the devserver to run the app locally
• check-npm-packages: check for packages not listed in the package.json, unused packages, and available updates
• format: lint and format the codebase
• i18n: extract translation keys
• lint: lint the codebase (component of format script)
• lint:styles: lint the CSS of the codebase
• storybook: start storybook
• test: run all tests
• test:coverage: generate test coverage report for unit/component/integration tests
• test:e2e: run end-to-end tests (headless)
• test:e2e:coverage: generate test coverage report for end-to-end tests
• test:e2e:ui: run end-to-end tests with user interface (for writing and debugging end-to-end test)