make-demo

name	make-demo
description	Create or revise demos in the Remix repository. Use when adding a new demo under demos/, updating an existing demo, or reviewing demo code to ensure it showcases Remix packages, strong code hygiene, and production-quality patterns.

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/ui 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/ui, prefer idiomatic Remix component patterns. Use normal JSX composition and built-in styling/mixin props such as css={...} or mix={css(...)} and mix={[...]} instead of dropping down to manual DOM mutation or ad hoc class management.
• When a demo uses remix/ui JSX, configure that demo's tsconfig.json with jsx: "react-jsx" and jsxImportSource: "remix/ui". 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/ui, use --import remix/ui-hmr/node for the child server and add uiHmr() to the asset server's loaders. Keep all HMR wiring development-only.
• For HTML responses rendered with remix/ui, prefer a local app/middleware/render.tsx middleware that uses renderWith(...), calls renderToStream(...), wraps it with createHtmlResponse(...) from remix/response/html, and lets actions render with context.get(Renderer)(...).
• 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

App layout

Inside app/, organize code by responsibility:

• actions/ for all controller-owned route actions and route-local UI/helpers. The root route map lives in actions/controller.tsx; nested route maps live in route-key folders such as actions/auth/controller.tsx or actions/account/controller.tsx
• data/ for runtime data definitions such as table schema and setup helpers used by the application at startup
• middleware/ for request-layer concerns such as auth, database injection, sessions, and other request lifecycle setup
• ui/ for shared UI primitives used across route areas
• utils/ for shared runtime support code that does not clearly belong to one of the other app layers

Naming and ownership rules

• Keep controllers thin. They should read request context, talk to the database or other runtime services, and return a response.
• actions/controller.tsx owns top-level leaf route actions, and each nested route map gets its own explicit actions/<route-key>/controller.tsx file. A controller's actions object contains direct leaf route keys from the route map passed to its router.map() call.
• Name directories under app/actions/ after route-map keys, not URL path segments.
• If a component or helper is only used by one controller feature, keep it in that controller feature folder.
• If UI is shared across route areas, keep it in app/ui/.
• Do not put shared UI under app/actions/, and do not create a generic app/components/ dumping ground.
• Do not create a generic app/lib/ dumping ground.
• Avoid feature barrel files such as index.ts. Import feature modules directly.
• If a non-UI helper is shared only by controllers, keep it under actions/.
• If a helper is part of request or session setup, keep it under middleware/.
• Keep table definitions, row types, and runtime database setup in app/data/.
• Keep database artifacts such as migrations and SQLite files in db/.
• Use utils/ only for genuinely cross-layer support code. Prefer a topic-specific name like utils/external-auth.ts over catch-all names like helpers.ts or misc.ts.
• Co-locate tests with the app modules they cover whenever those tests primarily exercise one implementation file or one small feature area.
• Use the root test/ directory only for shared test code, fixtures, and truly broad integration coverage that does not belong to a single app module.

Example layout

demos/<name>/
  app/
    router.ts
    router.test.ts
    routes.ts

    actions/
      controller.tsx

      auth/
        controller.tsx
        signup/
          controller.tsx
        resolve-external-auth.ts

      account/
        controller.tsx
        account-page.tsx

    data/
      schema.ts
      setup.ts
      setup.test.ts

    middleware/
      render.tsx
      auth.ts
      database.ts
      session.ts

    utils/
      auth-session.ts
      auth-session.test.ts
      password-hash.ts
      external-auth.ts

    ui/
      auth-card.tsx
      document.tsx
      form-field.tsx
      notice.tsx
      icons.tsx
      design-system.ts

  db/
    migrations/
    app.sqlite

  test/
    fixtures/
    helpers.ts

  public/
  tmp/

README Expectations

• Explain what the demo proves or teaches.
• Document how to run it locally.
• Point out the key Remix APIs or patterns being demonstrated.
• Keep code examples and imports aligned with repo guidance: use remix package exports where available.

Validation

• Run pnpm -C demos/<name> typecheck when the demo defines a typecheck script.
• Run pnpm -C demos/<name> test when the demo defines tests.
• Smoke-test the demo server locally when behavior depends on live requests or browser interaction.
• Smoke-test HMR demos through their hmr script when the change depends on live server or browser updates.
• Run pnpm run lint before finishing.