Skip to content

Add sideEffects field to package.json to enable bundler tree-shaking #886

@NoopDog

Description

@NoopDog

Parent: #885

Summary

package.json does not declare a sideEffects field. Without it, webpack/Turbopack conservatively assume every module in findable-ui may have side effects on import and cannot eliminate unused exports. Declaring \"sideEffects\": false (or an allowlist) tells the bundler it is safe to drop any imported module whose exports aren't actually used, which can substantially shrink consumer bundles.

Why this is zero-consumer-impact

sideEffects only changes how bundlers behave when compiling a consumer. The package's runtime behavior is unchanged. Consumers don't update any imports.

Research to do

  1. Confirm the lib is side-effect free. Grep the source for anything that runs at module-evaluation time beyond declaring/exporting:
    • CSS/SCSS imports (.css, .scss, global style imports) — a quick scan found none.
    • Polyfills imported for side effects.
    • window.X = ... or similar top-level mutations.
    • console.log / logger setup at module scope.
    • Self-registering modules (e.g., pushing onto a global registry on import).
    • Event listener attachments at module scope.
  2. Audit .styles.ts(x) — these should be pure emotion styled(...) definitions. Verify no module-scope side effects.
  3. Audit providers / reducers — module-scope createContext(...) is fine (pure). Confirm nothing dispatches or subscribes at import.
  4. Audit src/common/analytics — confirm the GA wiring is function-scoped, not side-effectful at import.
  5. Test consumer bundle — in a test consumer app (e.g. data-browser), capture a bundle-analyzer report before and after the change to confirm expected shrinkage and no regressions.
  6. Storybook smoke test — run storybook and confirm components still render.

Implementation options

Option A — full false:

\"sideEffects\": false

Preferred if the audit above finds no side effects. Maximum tree-shaking.

Option B — allowlist:

\"sideEffects\": [\"**/*.css\", \"**/*.scss\"]

Use if we discover specific files with required side effects. Those files are preserved even if only their side effect is imported; everything else can be dropped.

Default recommendation: Option A, unless audit surfaces counterexamples.

Testing

  • npm test, npm run lint, npm run test-compile pass.
  • Storybook renders all components.
  • In a consumer app: bundle analyzer before/after, look for dropped chunks. No visual regressions on key pages.

Acceptance criteria

  • Audit completed; any offending modules either refactored or added to the allowlist
  • sideEffects field added to package.json
  • Lint, tests, and tsc --noEmit pass
  • Storybook renders cleanly
  • Before/after bundle-analyzer screenshots from one consumer posted in PR

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions