This Gatsby starter boilerplate is a production-ready development environment combining TypeScript, SCSS modules with auto-generated typings, ESLint/Prettier formatting, Husky commit hooks, and Docker support.
What is this Gatsby starter?
It's a starting point for production Gatsby projects, built on Gatsby (React-based) and providing a pre-configured toolchain. It takes a fresh Gatsby project as a base and adds TypeScript, SCSS support with type generation, linting, and Docker workflows. The output is a project you can develop on and build statically with npm run build.
Key Features
- SCSS type generation — Auto-generates TypeScript definitions for
.scssfiles via awatchscript using chokidar andscripts/generateTypings.js, so you can import styles likeimport * as styles from './styles.module.scss'and get type hints. - Format & commit safety — ESLint, StyleLint, and Prettier are configured with Lint-Staged and Husky pre-commit hooks;
.vscode/settings.jsonenables formatting on save in VS Code. - Responsive breakpoints — Breakpoints are defined in
src/styles/constants/_breakpoints.scssand used with amediamixin, e.g.@include media('>=large') { ... }. - DRY styling — Constants for colors, spacings, and text sizes live in
src/styles/constants/, with functions and mixins to avoid repeated hardcoded properties. - Docker support —
docker-composemounts the gatsby directory (exceptnode_modules) for hot reloading;yarn devDockerruns the server with the network interface exposed. - Absolute imports — Import components without relative paths, e.g.
import Greeting from 'components/Greeting'. - NPM scripts —
build,devLocal,devDocker,watch,fix, andbuildScssTypingscover common development tasks.
Who is it for?
- Gatsby developers who want a TypeScript and SCSS setup without manually configuring tooling.
- Development teams that need consistent code style through enforced linting and formatting.
- Developers using Docker who want a containerized environment with live reload via mounted volumes.
What can you do with it?
- Start a new site quickly: install dependencies with
yarn, runyarn devLocal, and get a hot-reloading Gatsby server athttp://localhost:8000/. - Write typed SCSS: import style modules and receive TypeScript type definitions automatically.
- Run in Docker: build and start the container with
docker-compose buildanddocker-compose up.
How does it work?
After yarn installs packages, yarn devLocal launches the Gatsby dev server and a chokidar watcher that regenerates SCSS typings on file changes. yarn devDocker does the same inside Docker, exposing the full network interface. The watch script uses scripts/generateTypings.js to build .d.ts files for each .scss module.
Pros and cons
- Pros: Pre-configured linting and formatting, automatic SCSS type generation, responsive mixins, and Docker compatibility.
- Cons: According to the project's todo list, the typings script currently rebuilds all files rather than just changed ones, no test library is included yet, and the Docker setup has an unresolved item ("fix docker").
FAQ
How do I get started?
Run yarn to install all npm packages, then run yarn devLocal to start the Gatsby server plus the file watcher. Access the site at http://localhost:8000/.
How do I use Docker for development?
Build the image with docker-compose build, then start with docker-compose up. The gatsby directory is mounted so hot reload works, but if you add new packages you need to rebuild the container because installations happen during the build.
What is the watch script for?
yarn watch uses chokidar to watch all .scss files and runs buildScssTypings on every change, generating TypeScript definitions so you have type hints on imported style classes.
How do I add a new page template?
Create a template in src/templates/ and map it to a URL in src/gatsby/routes.ts. You can also add hooks like onCreatePage in src/gatsby/createPages.ts.
Does this starter include tests?
No, the project's todo list explicitly includes "add test library and showcase test driven development," so tests are not yet implemented.
