Add Package

Add Package

Overview

Use this skill to scaffold and standardize packages so they look and behave like the existing @remix-run/* packages. Follow this exactly when creating package files, public exports, tests, and docs.

Workflow

1. Create the package directory and baseline files.

• Create packages/<package-name>/.
• Add:
  • package.json
  • tsconfig.json
  • tsconfig.build.json
  • CHANGELOG.md
  • README.md
  • LICENSE
  • src/
• For new packages, start CHANGELOG.md with ## Unreleased as the first section to indicate changes are not released yet.

2. Set up package.json using monorepo conventions.

• Use:
  • name: @remix-run/<package-name>
  • version (for brand-new packages): "0.0.0"
  • type: "module"
  • license: "MIT"
  • repository.directory: packages/<package-name>
  • homepage: https://github.com/remix-run/remix/tree/main/packages/<package-name>#readme
• Include files:
  • LICENSE
  • README.md
  • dist
  • src
  • !src/**/*.test.ts
• Add standard scripts:
  • build: tsgo -p tsconfig.build.json
  • clean: git clean -fdX
  • prepublishOnly: pnpm run build
  • test: remix test
  • test:bun: bun x --bun remix test
  • typecheck: tsgo --noEmit
• Use baseline dev dependencies:
  • "@remix-run/assert": "workspace:^"
  • "@remix-run/test": "workspace:^"
  • "@types/node": "catalog:"
  • "@typescript/native-preview": "catalog:"
• Add keywords like existing packages (short, lowercase, feature-focused).
• Every published package must declare accurate sideEffects metadata. The generated remix package derives its metadata from each owning package, and package metadata validation rejects missing or invalid declarations.
  • Use "sideEffects": false only when evaluating every runtime module is free of observable side effects, including effects introduced by its imports.
  • Otherwise, list every effectful module using package-relative paths or glob patterns. Cover both source and emitted paths when the published package contains both, such as ./src/register.ts and ./dist/register.js.
  • Re-audit the field whenever runtime exports, top-level imports, or evaluation behavior changes. Registration, polyfills, global mutation, hook installation, event listeners, and effectful style imports are common reasons a module must be listed.

3. Define exports with src entry files only.

• In exports, map each public subpath to a dedicated file in src.
• Always include ./package.json.
• Mirror each export in publishConfig.exports with dist output:
  • types: ./dist/<entry>.d.ts
  • default: ./dist/<entry>.js
• Rule: every export must have a src file that re-exports from src/lib.
  • Example: export ./foo -> src/foo.ts -> export { ... } from './lib/foo.ts'
• Type-only exports may map only a types condition to src/*.d.ts and dist/*.d.ts.
• Runtime-specific exports may use package conditions before default when the runtime owns that condition, such as node-hmr for remix/node-hmr/runtime.
• If a package has type-only exports, add node ../../scripts/copy-package-type-only-exports.ts . to the package build script after tsgo.

4. Add TypeScript config files with shared defaults.

Use this tsconfig.json pattern:

{
  "compilerOptions": {
    "strict": true,
    "lib": ["ES2024", "DOM", "DOM.Iterable"],
    "module": "ES2022",
    "moduleResolution": "Bundler",
    "target": "ESNext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

Use this tsconfig.build.json pattern:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  },
  "include": ["src"],
  "exclude": ["src/**/*.test.ts"]
}

5. Implement source structure and test setup.

• Structure source as:
  • src/<entry>.ts for public entry points
  • src/lib/*.ts for implementation
  • src/lib/*.test.ts for tests (colocated with implementation)
• Tests use Remix's test runner:
  • import * as assert from '@remix-run/assert'
  • import { describe, it } from '@remix-run/test'
• Keep tests IDE-friendly:
  • Do not generate tests with loops/conditionals inside describe().

6. Follow monorepo code style rules while implementing.

• Use import type { ... } and export type { ... } for types.
• Include .ts extensions in relative imports.
• Prefer let for locals; use const only at module scope.
• Never use var.
• Prefer function declarations/expressions for normal functions.
• Use arrow functions for callbacks; use concise callbacks when returning a single expression.
• Use object method shorthand (method() {}) instead of arrow properties.
• Use native class fields and #private members.
• Avoid Node-specific APIs when Web APIs are available.