Boilerplate Astro + React

The Boilerplate Astro + React is an open-source starter template for building large, scalable static websites and web applications, combining Astro.js static site generation with React.js interactive components and TypeScript. It is maintained by Éverton Toffanetto on GitHub and aims to provide a standardized codebase with readability, reusability, and refactorability as core pillars.

What is the Boilerplate Astro + React?

This template is a fully configured project scaffold rather than a visual theme. As input it takes source code organized around a well-defined folder structure, and as output it produces a static Astro site with React islands, CSS Modules theming, unit and end-to-end tests, linting, and CI/CD workflows. The project runs on Astro.js with partial hydration, requires Node.js 22 or higher and the pnpm package manager, and is available under the GitHub repository everton-dgn/boilerplate_astro_react.

Key Features

• Atomic Design architecture — UI components are split into atoms, molecules, organisms, and layouts, creating a consistent and maintainable component hierarchy.
• Astro + React integration — Astro generates static HTML while React handles dynamic parts, with partial hydration to minimize JavaScript sent to the browser.
• TypeScript and CSS Modules — The project ships with TypeScript for type safety and CSS Modules for locally scoped, reusable styles.
• Testing setup — Vitest is preconfigured for unit and component tests, and Playwright covers end-to-end flows; both include watch, UI, and code-generation modes.
• Linting and formatting — BiomeJS provides fast linting and formatting, Lefthook runs checks only on changed files, and Commitlint enforces conventional commit messages.
• Performance optimizations — Each preloaded font is roughly 2 kilobytes, and Astro's island architecture keeps interactive code on demand.
• Icon system — Supports custom SVG icons and any icon from the Iconify collection, with full customization.
• CI/CD workflows — Pre-configured GitHub Actions automate release generation and versioning.

Who is it for?

• Developers building large-scale web projects — They get a pre-structured folder layout with atomic components, hooks, tests, and theme configuration ready to extend.
• Teams that enforce code quality — The combination of BiomeJS, Lefthook, and Commitlint standardizes formatting, linting, and commit messages across contributors.
• Developers who need tests from the start — Vitest and Playwright are already wired up, so unit and browser-level tests can be written immediately.
• Open-source contributors — The repository accepts pull requests that follow conventional commits, and tests are required for new features.

What can you do with it?

• Launch a production site quickly — Run pnpm build to generate a static Web site, then pnpm preview to serve it locally on http://localhost:4321.
• Develop with hot reload — Use pnpm dev to start the development server with verbose output available via pnpm dev:verbose.
• Run all tests — Execute pnpm test for Vitest, pnpm test:c for coverage, pnpm test:e2e for Playwright, and pnpm test:e2e:codegen to generate test code.
• Keep dependencies updated — The pnpm check:update script checks for available dependency updates.

How does it work?

The workflow starts by cloning the repository and installing dependencies with pnpm i. From there, the provided npm scripts handle development, production builds, testing, linting, formatting, and update checks. The source code is organized so components live in src/components under atomic layers, tests are placed next to components or in src/tests, and configuration files such as astro.config.ts, vitest.config.ts, playwright.config.ts, and biome.json are already in place.

FAQ

What Node.js version is required?

The boilerplate requires Node.js 22 or higher, with the LTS release recommended. It also relies on pnpm as its package manager, so the latest version of pnpm should be installed before running the scripts.

What testing frameworks are included?

Vitest is configured for unit and component testing, with support for coverage output, watch mode, and a UI dashboard. Playwright is set up for end-to-end testing and includes a code generator to create test scripts.

Does the boilerplate include TypeScript support?

Yes, the project is written in TypeScript. Type definitions live in the src/@types folder, and the tsconfig.json file is included for TypeScript configuration. You can run pnpm typecheck to validate types.

Is the boilerplate free to use?

The repository is publicly available on GitHub under the everton-dgn organization. The README does not mention any pricing, and the project carries a license badge, indicating it can be used as a base for professional projects.

Can I add my own icons?

Yes, the icon system supports custom SVGs and any icon set from Iconify. You can drop in your own SVGs or reference Iconify icons, making the icon set fully customizable.