Required dependencies

npm install typescript tsx
# Per-package peer dependencies (install only what you use):
npm install preact                        # component/
npm install @aws-sdk/client-s3            # file-storage-s3/
npm install memjs                         # session-storage-memcache/
npm install ioredis                       # session-storage-redis/
npm install better-sqlite3                # data-table-sqlite/
npm install mysql2                        # data-table-mysql/
npm install pg                            # data-table-postgres/

No native build steps, pod installs, or Android linking are required. All packages target the standard Web Fetch API and Node.js 18+.

Project setup

1. Copy the source/packages/ directory into your project root, e.g. packages/.
2. Add path aliases in tsconfig.json so local imports resolve correctly:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "strict": true,
    "paths": {
      "@remix/assert":                   ["./packages/assert/src/index.ts"],
      "@remix/async-context-middleware": ["./packages/async-context-middleware/src/index.ts"],
      "@remix/auth":                     ["./packages/auth/src/index.ts"],
      "@remix/auth-middleware":          ["./packages/auth-middleware/src/index.ts"],
      "@remix/node-fetch-server":        ["./packages/node-fetch-server/src/index.ts"],
      "@remix/fetch-router":             ["./packages/fetch-router/src/index.ts"],
      "@remix/session":                  ["./packages/session/src/index.ts"],
      "@remix/session-middleware":       ["./packages/session-middleware/src/index.ts"],
      "@remix/response":                 ["./packages/response/src/index.ts"],
      "@remix/headers":                  ["./packages/headers/src/index.ts"],
      "@remix/cookie":                   ["./packages/cookie/src/index.ts"],
      "@remix/cors-middleware":          ["./packages/cors-middleware/src/index.ts"],
      "@remix/csrf-middleware":          ["./packages/csrf-middleware/src/index.ts"],
      "@remix/form-data-parser":         ["./packages/form-data-parser/src/index.ts"],
      "@remix/multipart-parser":         ["./packages/multipart-parser/src/index.ts"],
      "@remix/mime":                     ["./packages/mime/src/index.ts"],
      "@remix/route-pattern":            ["./packages/route-pattern/src/index.ts"]
    }
  }
}

3. Run TypeScript files directly during development with tsx:

npx tsx src/server.ts

4. Set environment variables your chosen packages need (see each package's README). Common ones:

SESSION_SECRET=your-secret-here
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Public API

asyncContext / getContext

import { asyncContext, getContext } from '@remix/async-context-middleware'
import type { AsyncContextTypes, AsyncRequestContext } from '@remix/async-context-middleware'

asyncContext is a middleware that seeds an AsyncLocalStorage store for the current request. Call getContext() anywhere downstream—inside route handlers, service functions, or other middleware—to retrieve the typed per-request store without threading it through function arguments.

createGitHubAuthProvider / startExternalAuth / finishExternalAuth

import {
  createGitHubAuthProvider,
  startExternalAuth,
  finishExternalAuth,
} from '@remix/auth'
import type {
  GitHubAuthProviderOptions,
  GitHubAuthProfile,
  OAuthResult,
  StartExternalAuthOptions,
  FinishExternalAuthOptions,
} from '@remix/auth'

createGitHubAuthProvider returns an OAuthProvider configured for GitHub OAuth2. Pass it to startExternalAuth to produce a redirect Response, and to finishExternalAuth to exchange the callback code for tokens and a typed GitHubAuthProfile. Use the same pattern for Auth0, Google, Facebook, Microsoft, Okta, and X providers.

auth / requireAuth / createSessionAuthScheme

import { auth, Auth, requireAuth, createSessionAuthScheme } from '@remix/auth-middleware'
import type {
  AuthOptions,
  AuthScheme,
  GoodAuth,
  BadAuth,
  WithAuth,
  WithRequiredAuth,
  RequireAuthOptions,
} from '@remix/auth-middleware'

auth(options) is a middleware factory that evaluates one or more AuthSchemes and attaches an AuthState to the request. requireAuth wraps a handler and short-circuits with a 401/403 if the state is BadAuth. createSessionAuthScheme reads the session to determine identity, making it the standard scheme for cookie-session apps.

completeAuth / verifyCredentials

import { completeAuth, verifyCredentials, createCredentialsAuthProvider } from '@remix/auth'
import type { CredentialsAuthProviderOptions, CredentialsAuthProvider } from '@remix/auth'

verifyCredentials checks a username/password pair against the credentials provider. completeAuth finalizes any auth flow—external OAuth or credentials—and returns the resolved identity. Use these together when building a custom login form backed by a database.

Working examples

Scenario - GitHub OAuth login flow

A minimal two-route OAuth integration using the auth package directly with a Fetch-compatible router.

import { createGitHubAuthProvider, startExternalAuth, finishExternalAuth } from '@remix/auth'
import type { GitHubAuthProfile, OAuthResult } from '@remix/auth'

const github = createGitHubAuthProvider({
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  redirectURI: 'http://localhost:3000/auth/github/callback',
  scopes: ['read:user', 'user:email'],
})

// Route: GET /auth/github
async function handleGitHubLogin(request: Request): Promise<Response> {
  return startExternalAuth({ provider: github, request })
}

// Route: GET /auth/github/callback
async function handleGitHubCallback(request: Request): Promise<Response> {
  const result: OAuthResult<GitHubAuthProfile> = await finishExternalAuth({
    provider: github,
    request,
  })
  // result.profile contains GitHubAuthProfile
  console.log('Logged in as', result.profile.login)
  return new Response(JSON.stringify(result.profile), {
    headers: { 'Content-Type': 'application/json' },
  })
}

Scenario - Per-request async context for logging

Store a request-scoped correlation ID that any downstream function can read without prop-drilling.

import { asyncContext, getContext } from '@remix/async-context-middleware'
import type { AsyncContextTypes } from '@remix/async-context-middleware'

// Augment the shared context type (module augmentation pattern)
declare module '@remix/async-context-middleware' {
  interface AsyncContextTypes {
    requestId: string
  }
}

// Compose into your middleware chain
async function handleRequest(request: Request): Promise<Response> {
  return asyncContext(request, async () => {
    const ctx = getContext()
    ctx.requestId = crypto.randomUUID()
    return businessLogic()
  })
}

async function businessLogic(): Promise<Response> {
  const { requestId } = getContext()
  console.log(`[${requestId}] Processing`)
  return new Response('ok')
}

Scenario - Session-based auth middleware with requireAuth

Protect an API route so that only authenticated users can access it.

import { auth, requireAuth, createSessionAuthScheme } from '@remix/auth-middleware'
import type { WithRequiredAuth } from '@remix/auth-middleware'

const sessionScheme = createSessionAuthScheme({
  // options pointing at your session storage
  sessionKey: 'userId',
})

const authMiddleware = auth({ schemes: [sessionScheme] })

async function protectedHandler(
  request: Request & WithRequiredAuth
): Promise<Response> {
  const { identity } = request.auth
  return new Response(JSON.stringify({ user: identity }), {
    headers: { 'Content-Type': 'application/json' },
  })
}

// Wire them together
async function handleProtected(request: Request): Promise<Response> {
  return authMiddleware(request, () =>
    requireAuth(request as Request & WithRequiredAuth, protectedHandler)
  )
}

Scenario - Credentials-based login

import {
  createCredentialsAuthProvider,
  verifyCredentials,
  completeAuth,
} from '@remix/auth'
import type { CredentialsAuthProviderOptions } from '@remix/auth'

const credentialsProvider = createCredentialsAuthProvider({
  async verify({ username, password }) {
    // Replace with real DB lookup
    if (username === 'admin' && password === 'secret') {
      return { id: '1', username }
    }
    return null
  },
} satisfies CredentialsAuthProviderOptions)

async function handleLogin(request: Request): Promise<Response> {
  const formData = await request.formData()
  const result = await verifyCredentials({
    provider: credentialsProvider,
    username: String(formData.get('username')),
    password: String(formData.get('password')),
  })
  if (!result) return new Response('Unauthorized', { status: 401 })
  const identity = await completeAuth({ provider: credentialsProvider, result })
  return new Response(JSON.stringify(identity), {
    headers: { 'Content-Type': 'application/json' },
  })
}

File walkthrough

• assert/ - Assertion helpers; re-exports everything from lib/assert.ts and also exposes a default namespace import for convenience.
• async-context-middleware/ - Wraps AsyncLocalStorage into a middleware + getContext() accessor; exports AsyncContextTypes for module-augmentation-based typing.
• auth/ - Core OAuth2/OIDC/credentials flows; provider factories for Auth0, Facebook, GitHub, Google, Microsoft, Okta, X, and a generic OIDC provider.
• auth-middleware/ - Middleware layer on top of auth/; handles scheme evaluation, request annotation, and requireAuth guard.
• component/ - Benchmark harness comparing component-framework rendering (Preact reference included); not a production UI library.
• compression-middleware/ - Applies gzip/brotli compression to outgoing Response streams.
• cookie/ - Parses Cookie headers and serializes Set-Cookie values per RFC 6265.
• cop-middleware/ - Sets Content-Security-Policy and Permissions-Policy response headers.
• cors-middleware/ - Handles preflight and adds CORS headers to responses.
• csrf-middleware/ - Generates and validates CSRF tokens, integrates with sessions.
• data-schema/ - Runtime schema definitions for input validation.
• data-table/ - Pagination, sorting, and filtering logic for tabular data, database-agnostic.
• data-table-mysql/ - MySQL-specific query adapter for data-table.
• data-table-postgres/ - PostgreSQL-specific query adapter for data-table.
• data-table-sqlite/ - SQLite-specific query adapter for data-table.
• fetch-proxy/ - Proxies inbound Request to an upstream URL and returns the upstream Response.
• fetch-router/ - Pattern-based router that dispatches Request objects to handler functions.
• file-storage/ - Abstract interface for storing and retrieving File/Blob objects.
• file-storage-s3/ - S3 implementation of the file-storage interface via AWS SDK v3.
• form-data-middleware/ - Middleware that eagerly parses the request body as FormData.
• form-data-parser/ - Low-level streaming FormData parser usable outside middleware.
• fs/ - Web-API-compatible wrappers around filesystem read/write operations.
• headers/ - Utilities for merging, reading, and mutating HTTP Headers objects.
• html-template/ - Tagged template literal that produces an HTML Response with correct content-type.
• lazy-file/ - Constructs a File object lazily from a stream, deferring buffering until needed.
• logger-middleware/ - Logs method, URL, status, and duration for every request/response pair.
• method-override-middleware/ - Allows browsers to send PUT/DELETE via a hidden form field or header.
• mime/ - Maps file extensions to MIME types and vice versa.
• multipart-parser/ - Streaming multipart boundary parser used by form-data-parser.
• node-fetch-server/ - Bridges Node.js http.IncomingMessage / ServerResponse to the Fetch Request/Response model.
• remix/ - Aggregate package that re-exports all public Remix 3 APIs as a single remix entry point.
• response/ - Factory functions for common responses: json(), redirect(), notFound(), etc.
• route-pattern/ - Compiles URL patterns and extracts named parameters from matched paths.
• session/ - Defines the session data model, read/write accessors, and serialization.
• session-middleware/ - Loads and saves session data around each request using pluggable storage.
• session-storage-memcache/ - Memcache-backed session store using memjs.
• session-storage-redis/ - Redis-backed session store using ioredis.
• static-middleware/ - Serves files from a directory with correct MIME types and range support.
• tar-parser/ - Streaming TAR archive reader that yields entries as ReadableStreams.

Common pitfalls and fixes

• TypeScript moduleResolution mismatch: the packages use .ts extension imports internally; set "moduleResolution": "NodeNext" and "module": "NodeNext" in tsconfig.json or imports will fail to resolve.
• AsyncContextTypes not augmented: calling getContext() returns an untyped object by default; always declare interface AsyncContextTypes in a .d.ts or entry file to get type safety.
• OAuth callback URL mismatch: the redirectURI passed to a provider factory must exactly match the URI registered in the OAuth app settings, including trailing slashes; a mismatch causes a provider-side 400 error.
• Session secret not set: session-middleware and csrf-middleware require a secret for signing/encryption; omitting SESSION_SECRET causes runtime exceptions rather than a startup warning.
• S3 credentials not found at runtime: file-storage-s3 uses the AWS SDK default credential chain; in local dev you must set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION or provide a profile via ~/.aws/credentials.
• ESM/CJS interop with Node.js http adapters: node-fetch-server outputs ESM; if your top-level entry still uses require(), switch to "type": "module" in package.json or use a dynamic import() wrapper.

Vibe-coding prompt template

I have a copy of the Remix 3 library packages located in `./packages/` inside my project.
A usage guide is at `USAGE.md`. The upstream source is `remix-the-web` (remix_run_remix).

Please help me integrate these packages into my existing project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Identify which packages from `./packages/` are relevant to my use case:
   [DESCRIBE YOUR USE CASE HERE - e.g., "GitHub OAuth login, session storage with Redis, and CORS support for my Express-style Node.js server"].
3. Add the required `tsconfig.json` path aliases for only those packages.
4. Install any peer dependencies those packages need (listed in USAGE.md § Required dependencies).
5. Write a working integration file `src/server.ts` that:
   - Imports only real exported symbols shown in USAGE.md § Public API.
   - Wires up the selected middleware in the correct order.
   - Exports a `fetch`-compatible handler function.
6. Show me how to run it with `npx tsx src/server.ts`.
7. Point out any environment variables I need to set before running.

Do not invent package names or export names. Use only the symbols listed in USAGE.md.

License and credit

Each package includes its own LICENSE file (see source/<package-name>/LICENSE). The packages are MIT-licensed. Source and upstream maintainers: https://github.com/remix-run/remix. Upstream package distribution entry: remix-the-web.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。