Framework Folder

Framework Folder

The app/framework/ folder must contain zero app-specific logic. It should be self-contained enough to extract as a separate npm package at any time.

What Belongs in app/framework/

Only reusable abstractions that apply across any app built on this framework:

• Database connection and helpers (db.server.ts)
• Session management (sessions.server.ts)
• Flash messages (flash.server.ts)
• Email transport setup (email.server.ts) — the makeSendEmail factory, not app-specific email config
• Environment variable utilities (env.server.ts) — the makeTypedEnvironment factory and framework-only env schema
• Route controller helpers (controllers.server.ts) — act(), load()
• Auth utilities (auth.server.ts)
• Background job utilities (worker.server.ts) — makeJob, makeCronJob

What Does NOT Belong in app/framework/

• App-specific environment variables (e.g., SENDGRID_API_KEY, GOOGLE_*, AWS_*)
• App-specific business logic or domain models
• App-specific configurations (e.g., SMTP credentials, S3 bucket names)
• Anything that references app/business/ or app-specific modules

Import Direction

The dependency flow is strictly one-directional:

app/business/   → imports from → app/framework/
app/routes/     → imports from → app/framework/
app/email.server.tsx → imports from → app/framework/

app/framework/  → NEVER imports from → app/business/, app/routes/, or app-level files

Framework files may import from each other using relative paths (./env.server).

The Factory Pattern

When framework code needs app-specific configuration, expose a factory function that the app calls with its own config:

// app/framework/email.server.ts — framework provides the factory
function makeSendEmail(config: SMTPTransport.Options & { maildevPort: number; maildevWebPort: number }) {
  // ... generic email sending logic
}

// app/email.server.tsx — app provides specific config
const sendEmail = makeSendEmail({
  maildevPort: 1027,
  maildevWebPort: 1082,
  host: 'smtp.sendgrid.net',
  // ...
})

Litmus Test

Before adding anything to app/framework/, ask:

1. Would another app built on this framework need this?
2. Does it reference any app-specific modules or env vars?
3. Could this be published as part of a standalone npm package?

If the answer to #1 is no, or #2 is yes, or #3 is no — it belongs in app/ or app/business/ instead.

Where lessons go

Project-empirical lessons about this skill land in workflow-content/framework-folder.md through a pull request on the project — never by editing this file, which is regenerated on every upgrade. A lesson that turns out to be true of every project travels as an issue on the workflow package instead.