rocambille/start-express-react

This system is a full-stack web application starter kit built with Express, React, and SQLite, designed to provide a production-ready foundation for modern web development. It implements core application features including passwordless magic-link authentication, user profile management with avatar uploads, and a persistent item management module with soft-delete and range-based pagination. The architecture emphasizes security and reliability through CSRF protection, Zod-based validation, comprehensive API contract testing, and automated database migration tooling.

10 changes.

The project underwent a comprehensive restructuring to establish a production-ready template, upgrading core dependencies like Express, React, and TypeScript to their latest versions. This period focused on modernizing the stack with SQLite persistence, streaming server-side rendering, and robust security measures, while reorganizing the frontend and backend into modular, maintainable components.

21 changes.

This period focused on implementing the application's core features, including magic link authentication, user profile management, and item CRUD operations, alongside the necessary backend middleware and database migration tooling. Comprehensive test coverage was established across the React frontend, Express backend, and infrastructure scripts to ensure reliability and validate the new API contracts.

The repository now includes git hooks to enforce code quality and manage releases. A new pre-commit hook automatically runs type checking, linting (biome), and unit tests before each commit, ensuring code standards are met. Additionally, a new post-commit hook automatically creates a git tag (vX.Y.Z) whenever the version number in package.json is updated, streamlining the release process.

.git-hooks · high confidence

An empty directory for database migrations has been added at src/database/migrations, initialized with a .gitkeep file to ensure the folder is tracked in version control.

src/database/migrations · high confidence

The application now supports passwordless login via magic links. Users can request a one-time login link sent to their email (with optional DKIM signing), which, when verified, issues a 7-day HttpOnly JWT stored in a secure cookie. This change introduces the core authentication flow, including token generation, verification, and session management, while removing the previous authentication mechanism.

src/express/modules/auth · high confidence

This change introduces three new helper modules in src/react/helpers to support the application's data and UI logic. The cache.ts module provides a getOrFetch/forget pattern compatible with React's use() hook, enabling promise-based caching that respects HTTP Range headers for pagination. The datetime.ts module offers robust date/time conversion utilities (e.g., toInputDate, fromInputParts) that handle timezone conversions using the configured VITE\_TIMEZONE, ensuring consistent display and input handling. The mutate.ts module simplifies API interactions by providing a useMutate hook that automatically handles CSRF token retrieval, secure cookie management, and cache invalidation (via forget) followed by UI refresh after mutations.

src/react/helpers · high confidence

The React authentication layer has been restructured around a new MeContext that centralizes user session state and actions (magic-link login, logout, profile updates, avatar upload, and account deletion). This enables a new AccountPage that lets users update their email and name, upload or remove an avatar, log out, and permanently delete their account. A new VerifyPage handles magic-link token verification, and a FormError component provides consistent validation feedback across all forms.

src/react/components/auth · high confidence

This change introduces several new React components to the application's UI layer. It adds a DataRefreshContext to bridge cache invalidation with React re-renders, ensuring the UI updates after data mutations. A new ErrorPage component provides a root error boundary with a link back to the home page. Form validation is enhanced with a FormError component that displays Zod validation errors inline using Pico CSS. The navigation experience is updated with a NavBar component that uses React Router's NavLink for active states and displays an avatar for authenticated users. Additionally, a Pagination component is added to render page navigation links based on HTTP range headers, and a simple Home page component is introduced to demonstrate basic state handling and display the current date.

src/react/components · high confidence

The scripts directory now includes a new database migration system. The \database-migrate\ script applies pending SQL migrations from \src/database/migrations/\ in alphabetical order, tracking applied files via checksums in a new \\_migrations\ table, and supports a \--no-interaction\ flag for automated environments. The \database-reset\ script drops all existing tables and re-applies the schema, migrations, and seeder data in a single operation. These scripts rely on \database-helpers\ for file scanning, checksum computation, and table management, providing a robust way to manage database state changes and resets.

scripts · high confidence

The item feature now includes a complete set of React components for managing items, including a paginated list view (ItemList) that uses HTTP Range headers for efficient data retrieval, and dedicated pages for creating (ItemCreate), editing (ItemEdit), and viewing (ItemShow) individual items. The shared ItemForm component handles client-side validation using Zod schemas and displays inline errors. Access to create and edit actions is restricted to authenticated users, while delete functionality is available only to the item's owner, enforced via UI-level checks in the show view.

src/react/components/item · high confidence

This change introduces the core user profile module, providing authenticated endpoints to read, edit, and soft-delete the current user's account, as well as upload and delete an avatar image. The implementation includes a new \UserRepository\ that enforces soft-deletion semantics (ignoring deleted rows in queries) and handles avatar URL updates, alongside Zod-based validation for user data. Users can now manage their profile via \/api/users/me\ and handle avatar files via \/api/users/me/avatar\, with the system automatically cleaning up old avatar files upon replacement or deletion.

src/express/modules/user · high confidence

The environment configuration in src/env has been split into client.ts and server.ts to separate browser-accessible variables from server-side secrets. The client schema now validates only frontend variables like timezone and node environment. The server schema extends this to include application settings and introduces support for DKIM (DomainKeys Identified Mail) by validating SMTP\_URL, DKIM\_PRIVATE\_KEY, DKIM\_DOMAIN, and DKIM\_SELECTOR, with automatic resolution of the DKIM domain from the SMTP URL and handling of private keys from either inline strings or file paths.

src/env · high confidence

The item module has been refactored from an in-memory mock to a persistent architecture using a dedicated repository layer backed by SQLite. This change introduces soft-deletion semantics, where items are logically removed via a timestamp rather than physically deleted, ensuring they are excluded from standard queries. Additionally, the browse endpoint now supports HTTP Range requests (206 Partial Content), allowing clients to fetch specific slices of the item collection efficiently, while all mutations are protected by ownership-based authorization checks.

src/express/modules/item · high confidence

The application database backend has switched from MySQL to SQLite, managed via a new shared instance in src/database/index.ts that stores data in a centralized data folder. The schema (src/database/schema.sql) now defines user, magic\_link\_token, and item tables, introducing soft-delete capabilities via deleted\_at columns on the user and item tables. Additionally, a seeder file (src/database/seeder.sql) has been added to populate initial test data for users and items.

src/database · high confidence

The application now includes a new set of reusable middleware utilities in src/express/helpers. This introduces stateless CSRF protection using a double-submit cookie pattern (returning 401 on mismatch), a Zod-based validation middleware that supports multi-target parsing (body, query, params) and optional server-side injection into the request body, a configurable file upload handler using Multer with MIME type and size restrictions, and a generic parameter converter for loading entities from repositories. These changes centralize cross-cutting concerns and standardize how requests are secured, validated, and processed.

src/express/helpers · high confidence

The repository has been restructured into a production-ready template with comprehensive configuration files. A new .env.sample provides a clear guide for environment variables, including optional DKIM support for email deliverability. Docker support is standardized via compose.yaml and compose.prod.yaml, integrating Mailpit for local email testing. The build tooling has been updated: tsconfig.json now targets ES2024, Biome has been upgraded to v2.5 with VCS integration, and Vite is configured to run Vitest tests across both Node and JSDOM environments. Additionally, security is enhanced with Helmet and rate limiting, and the entry point (server.ts) now features a robust fetch patch for SSR cookie forwarding.

(repo-wide) · high confidence

The React frontend has been significantly reorganized to improve modularity and user experience. The previous simple layout and home/item pages have been replaced by a new global Layout component that wraps the application with authentication context (MeProvider) and data refresh capabilities. A new AccountPage and VerifyPage have been added to handle user account management and verification flows. Additionally, a centralized ErrorPage is now used to catch and display errors across all routes, ensuring a consistent user interface during failures. The routing structure has been updated to support these new features and better organize item-related routes.

src/react · high confidence

The Express routing layer has been restructured to centralize middleware configuration and route composition. The previous single-file router for items has been replaced by a new \routes.ts\ entry point that explicitly registers global middlewares (cookie parsing, CSRF protection, and JSON body parsing) in a specific order. This file now serves as the central hub for mounting feature-specific route modules (auth, items, users) and includes a new \/api/health\ endpoint for API availability checks and CSRF validation testing.

src/express · high confidence

The type definitions in src/types have been updated to support broader data structures and modular imports. The generic Json type now explicitly includes bigint alongside string, number, boolean, and null, ensuring correct serialization for large integers. Additionally, the Item and User types are no longer hardcoded inline but are dynamically imported from their respective schema modules (itemSchemas and userSchemas), while a declaration for CSS modules has been added to support styling imports.

src/types · high confidence

The server entry point now uses React Router's static handler to execute loaders and actions, allowing the application to properly handle data fetching and mutations during server-side rendering. Instead of rendering the entire HTML string at once, the server streams the HTML response using \renderToPipeableStream\, which reduces time-to-first-byte and improves perceived performance. The implementation also correctly propagates HTTP headers and status codes from route loaders and actions back to the Express response, ensuring redirects and error states are handled accurately.

src · high confidence

Added API contract tests for authentication, items, users, and health endpoints; Added comprehensive React test utilities and contract-based mocking; Added contract-driven API testing infrastructure for Express routes; Added test coverage for database and project scaffolding scripts; Added tests for React helper utilities; Added tests for client and server environment variable schemas; Added tests for installation environment and database setup; Added type definitions for API contract tests; Added unit tests for React components; Added unit tests for authentication and account management components; Added unit tests for item management components; Added unit tests for the deleteUploadedFile helper.

The project has been renamed from 'start-express-react' to 'starter' and bumped to version 2026.09.01, with a minimum Node.js requirement raised to 22.5.0. Core dependencies have been significantly upgraded: Express moved from v4 to v5, React and React DOM from v19.0.0 to v19.2.8, and React Router from v7 to v8. New security and utility packages were added, including helmet, express-rate-limit, compression, cookie-parser, jsonwebtoken, multer, nodemailer, and zod. The build toolchain was updated with Vite jumping from v6 to v8, TypeScript from v5 to v7, and Biome from v1 to v2. Testing infrastructure shifted to Vitest (v4) with React Testing Library, replacing previous setups. Several scripts were added or renamed to support new features like database migration, cloning, and purging.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 69 → 67 (-1.9)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 98 → 97 (-0.9)
• Architecture 99 → 100 (+1.1)
• Maturity 70 → 75 (+5.7)
• Readiness 59 → 53 (-6.0)
• Security 99 → 99 (-0.3)
• Accessibility 69 → 71 (+1.9)

• Change coupling: NavBar.tsx ↔ routes.tsx (src/react/components/NavBar.tsx)
• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Medium IaC: CKV_DOCKER_3 (Dockerfile)
• No exposed public API
• Off-boarding risk: anonymized user #1
• Test reliability not included

• Coverage not measured — JavaScript/TypeScript suite
• Documentation: no installation or build instructions (README.md)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Hotspot: tests/express/test-utils.ts (tests/express/test-utils.ts)
• Low IaC: DS-0026 (Dockerfile)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium IaC: WD-COMPOSE-0002 (compose.yaml)
• Medium IaC: WD-DOCKER-0003 (Dockerfile)
• No ADRs found
• No assertions (empty test): should display inline errors when submitting invalid data (tests/react/components/item/ItemForm.test.tsx)
• No assertions (empty test): should mount successfully (tests/react/components/auth/VerifyPage.test.tsx)
• No assertions (empty test): should mount successfully (tests/react/components/item/ItemForm.test.tsx)
• No assertions: should count (tests/react/components/Home.test.tsx)
• No assertions: should display Previous and Next when needed (tests/react/components/Pagination.test.tsx)
• No assertions: should display all page numbers when needed (tests/react/components/Pagination.test.tsx)
• No assertions: should display inline errors when email is invalid (tests/react/components/auth/MagicLinkForm.test.tsx)
• No assertions: should display inline errors when submitted data is invalid (tests/react/components/auth/AccountPage.test.tsx)
• No assertions: should display inline errors when uploaded file is invalid (tests/react/components/auth/AccountPage.test.tsx)
• No assertions: should display link to create item when authentified (tests/react/components/item/ItemList.test.tsx)
• …and 41 more

• 24 commits — 17 feature/other, 7 fixes

• (root) — 7 commits
• src/react — 7 commits
• src/express — 3 commits
• tests/express — 2 commits
• (repo) — 1 commit
• scripts/database-helpers.ts — 1 commit
• src/database — 1 commit
• src/env — 1 commit
• tests/contracts — 1 commit

• fix: fixed AGENTS.md after HTTP ranges usage
• fix: fixed README files
• fix: fixed avatar_url validation for relative urls
• fix: fixed datetime format in SQLite to match ISO 8601
• fix: fixed deprecated usage of zod and removed useless .entries() calls on form data objects
• fix: fixed formating
• fix: fixed missing deleteUploadedFile in tests
• change: Merge pull request #63 from rocambille/dev
• change: added DKIM support
• change: added empty migrations folder
• change: added file upload through avatar feature
• change: cleaned item contracts
• change: completed file upload tests
• change: implemented pagination using HTTP ranges
• change: minor change
• change: minor changes in md files
• change: moved express csrf stuff into helpers folder
• change: refactored AuthContext as MeContext
• change: refactored types and zod usage
• change: refined react-side zod schemas
• …and 4 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

rocambille/start-express-react was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.