BigfootDS ReactJS Multiplatform Template

This is a browser-first React template for products that also need desktop and mobile builds. Vite builds the web app, Electron packages it for desktop, and Capacitor syncs the same web output into native mobile projects.

The important bit is that src/ remains a normal web application. Desktop and mobile code sit at the edges, not inside every component.

flowchart TD
    A[React app in src/] --> B[Vite build]
    B --> C[dist/ static web app]
    C --> D[Browser]
    C --> E[Capacitor Android and iOS]
    C --> F[Electron Windows, macOS, and Linux]

Loading

Quick start

npm install
npm run react:dev

Then open the local URL printed by Vite. Before handing work over, run:

npm run react:lint
npm run react:test:e2e

The end-to-end command builds the app, starts a production preview on 127.0.0.1:4173, and runs the Chromium smoke test.

Common commands

What you need to do	Command
Start the browser development server	npm run react:dev
Build the web app and Electron main/preload bundles	npm run react:build
Preview the production web build	npm run react:preview
Run type-aware linting	npm run react:lint
Generate per-language localisation files	npm run localisation:split
Generate the dependency licence snapshot	npm run project:npmcompliance:update
Generate the Git contributor snapshot	npm run project:contributors:update
Synchronise Android version fields from package.json	npm run capacitor:version:sync
Check Android version fields against package.json	npm run capacitor:version:check
Create an ignored local environment template	npm run setup:env
Run the Playwright browser suite	npm run react:test:e2e
Open the Playwright test UI	npm run react:test:e2e:ui
Synchronise and build Android	npm run capacitor:android:build
Build a locally signed Android AAB	npm run capacitor:android:build:signed
Build a Windows portable Electron package	npm run electron:build:windows:portable

Project layout

Path	Purpose
src/	Browser-safe React application code.
electron/	Electron main-process and preload code.
android/	Capacitor-generated Android project.
public/	Static web assets.
tests/e2e/	Playwright end-to-end tests.
documentation/	Architecture, workflow, and adoption notes.
capacitor.config.json	Capacitor application configuration.
electron-builder.json5	Desktop packaging configuration.

Creating a project from this template

Before publishing a real product, replace the template identity in package.json, capacitor.config.json, and electron-builder.json5. Give the app a real name, package ID, icons, and release output names.

Set up signing outside the repository. Run npm run setup:env, add your local Android signing values to the ignored .env.local file, then use npm run capacitor:android:build:signed when you need an installable release build. CI reads the equivalent values from repository secrets. The checked-in configuration must never contain a real keystore, password, or production API key. CI and releases has the full local and CI setup.

If you need platform behaviour, read Platform architecture first. It explains where browser, Electron, and Capacitor code belongs.

Contributor guidance and documentation

AGENTS.md is the working agreement for AI agents and human contributors. It covers architecture boundaries, generated output, verification, and documentation expectations.

Keep focused repository guides in the lowercase documentation/ folder. Use lowercase kebab-case filenames, such as platform-architecture.md; README.md and AGENTS.md are the root-level entry points.

The focused guides are:

• Platform architecture
• Testing
• Persistence strategy
• SQLocal and Kysely settings recipe
• UI and theming
• Localisation
• Credits and licence data
• CI and releases
• Metadata, assets, and optional integrations
• Godmaker dogfooding adoption backlog

The backlog is deliberately separate from the guidance. It records unfinished template work as concrete checkbox tasks, rather than treating every useful idea as a mandatory dependency.