Make Demo

Make Demo

Overview

Demos in this repository are not throwaway prototypes. They are durable code artifacts that should teach people and other agents how to write Remix code well.

A good demo should:

• exercise Remix framework behavior in a realistic way
• push the target APIs through meaningful edge cases and composition points
• model clean structure, naming, and accessibility
• be code that a reader could adapt into a real application

Workflow

1. Read the target APIs and at least one or two existing demos before writing new code.
2. Choose a focused scenario that exists to demonstrate Remix behavior, not a generic app shell.
3. Build the demo under demos/<name>/ using the same conventions as the existing demos.
4. Treat the code as a reference artifact, not as temporary sample code.
5. Validate the demo locally before finishing.

Rules

• Use Remix library packages for the demo's framework behavior. Do not introduce unrelated routers, component frameworks, state managers, or middleware stacks that distract from the Remix patterns being demonstrated.
• Treat each demo as its own pnpm workspace consumer. Give it a normal package.json with remix as a dependency when appropriate, and import from package exports such as remix/component instead of reaching back into packages/ with relative imports.
• Keep any non-Remix dependency incidental to the runtime environment only. If a database driver, asset bundler, or type package is needed, it should support the demo rather than define its architecture.
• Demos should push Remix to its limits in a focused way. Prefer realistic edge cases, composition, streaming, middleware, routing, navigation, forms, or request-handling scenarios over toy examples.
• When demos use remix/component, prefer idiomatic Remix component patterns. Use normal JSX composition and built-in mixins such as css(...), on(...), and mix={[...]} instead of dropping down to manual DOM mutation or ad hoc class management.
• When a demo uses remix/component JSX, configure that demo's tsconfig.json with jsx: "react-jsx" and jsxImportSource: "remix/component". Do not set preserveSymlinks or add paths entries that point back into packages/remix/src. The goal is for TypeScript to resolve remix through the demo's own package dependency under pnpm's default symlink behavior.
• For demos that run through remix/node-tsx, do not enable erasableSyntaxOnly; the runtime intentionally supports TypeScript syntax that needs transformation.
• Treat development HMR as an optional mode for rapid UI edits. Keep server.ts as the real app server, keep pnpm dev running it directly, and put remix/node-hmr supervision in hmr.ts behind a pnpm hmr script. Use a stable public proxy with createHmrReadyFetch() when browser requests can race child server restarts.
• For demos that combine HMR with remix/component, use --import remix/component-hmr/node for the child server and add componentHmr() to the asset server's loaders. Keep all HMR wiring development-only.
• For HTML responses rendered with remix/component, install render() from remix/middleware/render in the router middleware stack and let actions render with context.render(...). Pass the app asset server as render({ assets }) when components use source-based clientEntry() modules. Use renderWith(...) only when the demo intentionally teaches a custom renderer contract or response pipeline.
• Prefer direct use of Remix and package APIs in demo code. Do not add custom wrappers around simple calls like session.get(), session.set(), session.flash(), session.unset(), redirect(), or context.get(...) unless the wrapper adds real domain logic, reusable policy, or a genuinely clearer abstraction.
• Demo code must have good hygiene. Use clear names, small focused modules, explicit control flow, and accessible markup. Avoid hacks, dead code, unexplained shortcuts, or patterns that would be poor examples for users to copy.
• Make the demo teach good patterns. Assume readers and future agents will study it as an example of how Remix code should be written in this repository.
• All demo servers should use port 44100.
• Demo servers should handle SIGINT and SIGTERM cleanly by closing the server and exiting.

Typical Structure

Use only the files the scenario needs, but prefer this shape:

• demos/<name>/package.json
• demos/<name>/tsconfig.json when the demo has TypeScript or JSX source
• demos/<name>/server.ts
• demos/<name>/hmr.ts when the demo offers an optional development HMR runner
• demos/<name>/README.md
• demos/<name>/app/
• demos/<name>/public/ when serving built assets or other static files

Remix Application Layout

When a demo is a real application, prefer a uniform Remix application layout instead of inventing a new structure for each demo.

Root layout

Use these root directories consistently:

• app/ for runtime application code
• db/ for database artifacts such as migrations and local SQLite files
• test/ for shared test helpers, fixtures, and any true cross-application integration tests
• public/ for static files served as-is
• tmp/ for runtime scratch files such as sessions, uploads, and caches