typescript-esm-conventions

TypeScript and ESM Conventions

Follow these TypeScript and ESM patterns for consistency across the Rempts codebase.

Module System

• Always use ESM imports/exports, never CommonJS (require/module.exports)
• Use .js extensions for all local imports (ESM requirement)
• Prefer named exports over default exports for better tree-shaking

// ✅ Good - ESM with .js extensions for local files
import { defineCommand } from '@reliverse/rempts'
import { validateConfig } from './utils/validation.js'

// ✅ Good - Named exports
export { myFunction, MyClass }

// ❌ Avoid - CommonJS
const { defineCommand } = require('@reliverse/rempts')

// ❌ Avoid - Missing .js extension for local imports
import { helper } from './helper'

File Naming

• Use kebab-case for all files: config-parser.ts, user-input.ts
• Test files: my-feature.test.ts
• Type definition files: api-types.ts
• Never use PascalCase or camelCase for file names

Type Safety

• Use strict TypeScript configuration from tsconfig.base.json
• Define types in packages/core/src/types.ts for shared interfaces
• Use type inference where possible, explicit types where clarity is needed
• Leverage the plugin type system in packages/core/src/plugin/types.ts

Plugin Type Patterns

// Define store types for plugins
interface MyPluginStore {
  data: string[]
  count: number
}

// Use createPlugin with generics for type safety
const myPlugin = createPlugin<MyPluginStore>({
  name: 'my-plugin',
  store: {
    data: [],
    count: 0
  },
  beforeCommand({ store }) {
    // TypeScript knows store.data is string[]
    store.data.push('command')
  }
})

// For plugin factories with options
const myPlugin = createPlugin<Options, Store>((options) => ({
  // Plugin definition
}))

Package Development

• Each package has its own package.json with proper ESM configuration
• Use "type": "module" in package.json
• Build scripts are in scripts/build.ts using Bun's bundler
• Export types and runtime code separately when needed