Gatsby TypeScript SCSS Docker

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 .scss files via a watch script using chokidar and scripts/generateTypings.js, so you can import styles like import * 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.json enables formatting on save in VS Code.
• Responsive breakpoints — Breakpoints are defined in src/styles/constants/_breakpoints.scss and used with a media mixin, 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-compose mounts the gatsby directory (except node_modules) for hot reloading; yarn devDocker runs 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, and buildScssTypings cover 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, run yarn devLocal, and get a hot-reloading Gatsby server at http://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 build and docker-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.