TypeScript 1,379 FILES 12 FINDINGS

HOW REMIX
ACTUALLY WORKS

Build better websites. The full stack web framework from Shopify. Conventions, patterns, and architecture extracted from the remix-run/remix repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Testing: Node.js built-in test runner Auth: auth middleware Exports: Named exports preferred

WHAT_MATTERS

→
Strongly prefers named exports over default exports (39:1 ratio) — use export function, not export default
→
demos/bookstore/app/routes.ts is a hub file (imported by 53 files) — changes here ripple everywhere
→
Auth uses auth middleware — logic lives in packages/auth-middleware/src/index.ts

KEY_FINDINGS

This is a monorepo. Changes may affect multiple packages.

HIGH

Tests are co-located with source files. Keep this pattern — don't create a separate test/ directory.

HIGH

Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.

HIGH

24 barrel export files found

Environment variables are documented in .env.example. Copy it to .env.local before running.

HIGH

Strongly prefers named exports over default exports (39 named vs 1 default). Use export function, not export default.

HIGH

Tests use Node.js built-in test runner.

HIGH

11 test files

Auth uses auth middleware. Auth logic lives in packages/auth-middleware/src/index.ts.

HIGH

4 files

Generated files detected (packages/mime/scripts/codegen.ts, etc). Do NOT edit directly.

HIGH

2 generated files

UI components live in: demos/sse/app/ui, demos/social-auth/app/ui, demos/frames/app/ui.

HIGH

3 component directories

Hub files: demos/bookstore/app/routes.ts (53 files); demos/bookstore/app/data/schema.ts (38 files); demos/bookstore/app/ui/layout.tsx (23 files); packages/component/src/lib/jsx.ts (22 files); demos/bookstore/app/utils/render.tsx (19 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: parse.ts → part-pattern.ts; route-pattern.ts → part-pattern.ts → parse.ts; route-pattern.ts → part-pattern.ts → href.ts. Avoid adding to these cycles.

HIGH

83 dead code candidates detected. Review and clean up unused exports.

HIGH

smart_toy USING_AI_TOOLS

→use named exports, not default exports
→check auth middleware before modifying auth flows
→don't edit generated codegen files directly

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **testing:** Tests use Node.js built-in test runner.
- **auth:** Auth uses auth middleware.
- **exports:** Named exports preferred (39:1 ratio).

## Commands

- **Build:** `pnpm -r build`
- **Test:** `pnpm --parallel run test`
- **Lint:** `oxlint . -A all --quiet`

## Critical Constraints

- **Monorepo:** This is a monorepo. Changes may affect multiple packages.
- **Testing:** Tests are co-located with source files. Keep this pattern.
- **Exports:** Strongly prefers named exports over default exports (39:1 ratio).
- **Generated files:** Do NOT edit generated files (packages/mime/scripts/codegen.ts, etc) directly.
- **Circular dependencies:** Circular import chains detected: parse.ts → part-pattern.ts; route-pattern.ts → part-pattern.ts → parse.ts. Avoid adding to these cycles.
- **Core modules:** Hub files (most depended on): demos/bookstore/app/routes.ts (53 files); demos/bookstore/app/data/schema.ts (38 files); demos/bookstore/app/ui/layout.tsx (23 files). Changes here have the widest blast radius.

## Stack

React, Express, TypeScript

## Core Modules (by structural importance)

- `packages/component/src/lib/component.ts`
- `packages/component/src/lib/jsx.ts`
- `packages/auth/src/lib/provider.ts`
- `demos/bookstore/app/routes.ts`
- `demos/bookstore/app/data/schema.ts`

## Conventions & Patterns

- **Import conventions:** Project uses barrel exports (24 barrel export files). Import from the directory, not from deep paths.
- **Export conventions:** Strongly prefers named exports over default exports.
- **Dominant patterns:**
- Tests use Node.js built-in test runner.
- Auth uses auth middleware.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

NEXT.JS SVELTEKIT

HOW REMIXACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW REMIX
ACTUALLY WORKS