Sudoku ·

Web app based on SolidStart, Solid.js, and Vinxi, powered by a Nix-based development environment.

---

Table of content

• Prerequisites
• Setup
• Stack
• Architecture
• Testing
• CI
• Scripts
• Deployment

---

Prerequisites

• Nix - A powerful package manager for reproducible builds.
• direnv - A shell extension that automatically loads and unloads environment variables, integrating seamlessly with Nix.

For a smooth development experience, ensure Nix and direnv are installed and configured on your system.

Install Nix:

On macOS and Linux, install Nix using the recommended multi-user installer. For the most up-to-date and detailed instructions, refer to the official Nix installation guide.

sh <(curl -L https://nixos.org/nix/install) ---daemon

Follow the on-screen prompts to complete the installation.

Configure direnv hook:

After installing direnv, you need to integrate it with your shell. For the most accurate and up-to-date instructions for your specific shell, consult the direnv documentation on shell integration. Add the following line to your shell's configuration file (e.g., ~/.bashrc for Bash, ~/.zshrc for Zsh, or ~/.config/fish/config.fish for Fish):

eval "$(direnv hook <your_shell_name>)"

Replace <your_shell_name> with your actual shell (e.g., bash, zsh, fish). After adding the hook, restart your terminal or source your shell's configuration file (e.g., source ~/.bashrc) for the changes to take effect. This enables direnv to automatically load and unload the project's development environment defined in flake.nix when you navigate into the project directory.

Setup

This project uses Nix and direnv for managing its development environment, including Node.js and Bun versions.

Allow direnv to load the Nix environment:

direnv allow

This command, when run in the project root, will read flake.nix and provision the development environment, including Bun and Node.js. The .bun-version and .node-version files will be automatically updated by the flake.nix shell hook to reflect the versions provided by Nix.

Install dependencies using Bun:

bun install

(Bun is provided by the Nix development environment)

Copy environmental variables (if applicable):

cp .env.example .env

Start the development server:

bun run dev

Stack

Framework & Libraries

• Solid.js - A reactive UI library for building user interfaces.
• SolidStart - A Solid.js meta-framework for fullstack applications.
• Vinxi - The full-stack web framework that powers SolidStart, providing bundling and server capabilities.
• TypeScript - Typed language built on top of JavaScript.

Development Tools

• Nix - For reproducible development environments and package management.
• Bun - A fast all-in-one JavaScript runtime, bundler, test runner, and package manager.
• ESLint - Static code analysis for identifying problematic patterns.
• Oxlint - A fast Rust-based linter.
• Prettier - An opinionated code formatter.
• Wrangler - Cloudflare's CLI tool for developing and deploying Workers and Pages.
• d2 - Declarative Diagramming for turning text into diagrams.

---

Architecture

This project follows a layered architecture pattern with clear separation of concerns and unidirectional dependency flow. The architecture is designed to be framework-agnostic at the core, with framework-specific concerns isolated to outer layers.

For detailed overview see Architecture Documentation.

---

Testing

This project employs a comprehensive testing strategy using Vitest for unit and browser-based component tests, and Playwright for end-to-end (E2E) tests.

Testing Structure

• Unit Testing: Vitest runs unit tests (*.spec.ts) in Node.js environment for utilities and logic testing (22 test files)
• Browser Testing: Vitest with Playwright provider runs component tests (*.spec.browser.tsx) in Chromium for UI components (1 test file)
• End-to-End Testing: Playwright executes E2E tests in e2e/ directory against the built application using Wrangler preview server
• Page Objects: Shared page object pattern with adapters for both Vitest and Playwright test environments

Test Configuration

• Unit Tests: Run in Node.js environment with SolidJS Testing Library setup
• Browser Tests: Run in headless Chromium with 5-second timeout
• E2E Tests: Run against http://localhost:8787 (Wrangler preview) with retry logic in CI
• CI Integration: Tests run in GitHub Actions with proper browser installation and artifact management
• Vitest setup: all vitest setup files defined in test folder
• Page Objects setup: all page object adapters are defined in test folder

For detailed commands, see the Testing Scripts section.

---

CI

The project uses GitHub Actions for Continuous Integration, defined in .github/workflows/ci.yml. The CI pipeline runs on every pull request and push to the main branch, ensuring code quality and stability with automatic deployment to Cloudflare.

The CI workflow includes the following jobs:

• install-dependencies: Installs project dependencies using Bun.
• install-browsers: Installs Playwright browser binaries for E2E testing.
• quality-checks: A matrix job running parallel quality checks.
• test-unit: Executes unit tests using Bun.
• test-browser: Runs browser-based component tests using Vitest.
• build: Creates production build and uploads artifacts.
• e2e: Downloads build artifacts and runs Playwright E2E tests.
• deploy: Automatically deploys to Cloudflare using Wrangler after successful builds.

Dependabot

This repository uses Dependabot to keep dependencies secure and up to date. Dependabot automatically creates pull requests for:

• JavaScript/TypeScript dependencies managed by Bun
• GitHub Actions workflows

These pull requests ensure that the project remains secure and compatible with the latest stable versions of its dependencies. Configuration for Dependabot is stored in .github/dependabot.yml.

Code Owners

A .github/CODEOWNERS file is included to define responsibility for reviewing and approving changes. Pull requests affecting specific parts of the repository automatically request reviews from designated owners.

---

Scripts

Summary of bun run scripts defined in package.json.

Development & Build

Script	Description
build	Builds the application for production deployment.
dev	Starts the development server with hot module reloading.
start	Serves the built production application locally.
preview	Previews the production build locally using Wrangler.

Testing

Script	Description
test:unit	Runs unit tests in watch mode using Vitest.
test:unit:run	Runs unit tests once using Vitest.
test:browser	Runs browser-based component tests via Vitest.
test:browser:run	Runs browser-based component tests once.
test:e2e	Runs Playwright E2E tests against preview server.
test:e2e:dev	Runs E2E tests with UI against development server.
test:install:browsers	Installs Playwright browser binaries (Chromium).
test:install:deps	Installs OS dependencies for Playwright browsers.

Code Quality & Formatting

Script	Description
check:format	Checks code formatting with Prettier.
fix:format	Automatically fixes formatting issues with Prettier.
check:lint	Runs all linters (ESLint and Oxlint).
fix:lint	Automatically fixes linting issues.
fix:lint:eslint	Automatically fixes ESLint issues.
fix:lint:oxlint	Automatically fixes Oxlint issues.
lint:eslint	Lints TypeScript files with ESLint.
lint:oxlint	Lints files with Oxlint.
check:types	Validates TypeScript types across the project.
check:cf-types	Verifies Cloudflare types are up-to-date.
lighthouse	Runs Lighthouse performance audits.

Code generation

Script	Description
generate:diagrams	Generates D2 diagrams from source
generate:cf-types	Generates TypeScript types for Cloudflare configuration.
postgenerate:cf-types	Post-generation check for outdated types in CI.

Tools

Script	Description
wrangler	Direct access to Wrangler CLI.

---

Deployment

For comprehensive deployment information, environment management, and rollback procedures, see Deployment Guide