molcrafts-index

React/TypeScript application for molcrafts.org. This document is the engineering map for maintainers and coding agents.

Requirements

• Node.js 22 (see .node-version)
• npm

The repository intentionally does not commit package-lock.json; use npm install, not npm ci.

Commands

Command	Purpose
npm install	Install dependencies
npm run dev	Start the local Rsbuild server
npm run build	Build the site and run all post-build generators
npm run preview	Serve the production output locally
npm run lint	Run Biome over src/ and scripts/
npm run typecheck	Type-check application and build scripts
npm test	Run the Rstest unit suite

Before merging, run:

npm run lint
npm run typecheck
npm test
npm run build

Runtime architecture

src/main.tsx
  └─ providers and global styles
     └─ src/App.tsx
        ├─ /                 → components/home/HomePage.tsx
        ├─ /<product-slug>   → package GitHub repository
        └─ other paths       → pages/NotFound.tsx

• src/components/home/ owns the homepage composition and sections.
• src/lib/home/copy/ owns localized homepage copy and copy types.
• src/lib/home/data.ts owns homepage section and sponsor data.
• src/lib/ecosystem.ts and src/lib/packages.ts own the product catalog and repository targets.
• src/lib/routes.ts owns retired product slugs and client-side redirects.
• src/styles/ owns Tailwind entry styles and shared brand tokens.
• src/components/ui/ contains the shadcn/Radix primitives used by product components.

The application uses a small client-side router in src/App.tsx; there is no route framework or server runtime.

Build pipeline

npm run build runs Rsbuild and then scripts/postbuild.ts:

1. generate Open Graph images;
2. prerender route HTML;
3. generate llms.txt.

Generated output is written to dist/ and is never committed. Static deployment files live in public/; public/_redirects mirrors the client-side product redirects for the hosting layer.

Engineering conventions

• Use the @/ alias for src/; it is shared by TypeScript, Rsbuild, Rstest, and shadcn.
• Compose class names with cn() from src/lib/utils.ts.
• Reuse motion variants from src/lib/animations.ts.
• Keep unit tests under tests/; browser regressions belong under regressions/.
• Keep build-time scripts in the TypeScript gate. They consume application types and run during production builds.
• Do not commit dist/, local tool state, browser captures, or agent runtime configuration.

Environment

PUBLIC_GA_ID optionally enables Google Analytics. Copy .env.example to .env for local overrides. Every PUBLIC_* value is shipped to the browser and must not contain secrets.

CI and deployment

GitHub Actions uses Node 22 and runs install, lint, and typecheck. Local pre-commit hooks mirror lint and typecheck; tests and the production build are the merge gate.

The production artifact is the dist/ directory generated by npm run build.

License

MIT — see LICENSE.