Repo guidance: Test-only exports

Packages sometimes leak test utilities or mocks through their public entry point. This silently expands API surface and increases bundle size.

Problems

• Accidental API churn when internal test helpers change.
• Larger dependency graph for consumers (unused code retained) with non-browser code.
• Risk of consumers taking dependencies on unstable internals.
• Jest / test framework references end up in browser bundles causing runtime errors or extra polyfills.

Recommended pattern

Keep test helpers out of the main entry by creating a separate test-only entry file (e.g. index.test.ts or index.mock.ts) that re-exports only the symbols intentionally exposed for tests. Do not export these from the main index.ts.

Example layout:

src/
  index.ts              <-- production entry (no test imports)
  index.test.ts         <-- ONLY re-exports test helpers
  test/
    createMockStore.test.ts
    renderWithTheme.test.ts

src/index.test.ts:

export { createMockStore } from './test/createMockStore.test'
export { renderWithTheme } from './test/renderWithTheme.test'

Partial exports map in package.json:

{
  "name": "some-pkg",
  "exports": {
    // Paths and supported conditions will vary with your setup
    ".": {
      "source": "./src/index.ts",
      "types": "./lib/index.d.ts",
      "import": "./lib/index.js",
    },
    "./test": {
      "source": "./src/index.ts",
      "types": "./lib/index.d.ts",
      "import": "./lib/index.js",
    },
  },
}

Usage in other-pkg/src/something.test.ts:

import { createMockStore, renderWithTheme } from 'some-pkg/test'

Rationale:

• Keeps any Jest (or other test framework) references isolated; the main bundle never parses them.
• Makes intent explicit: anything under the test entry is unstable and not part of the supported runtime API.
• Allows tree shaking to ignore test helpers entirely for builds.

Avoid

• Importing Jest (or other test libs) from main entry.
• Re-exporting ./index.test symbols via the main entry.
• Using wildcard export * in the test entry (be explicit to avoid accidental leakage).

Enforcement

no-test-exports lint rule to bans exporting paths or names which appear to be test-related from index files.