MobX 6 decorator support: choosing between transpiler legacy config and makeObservable migration

Direct recommendation

Migrate stores to makeObservable or makeAutoObservable in constructors. Keep legacy decorator transpilation only as a temporary bridge for untouched code. For long-term stability, remove the legacy decorator build dependency.

Confirmed facts

• MobX 6 removed built-in decorator compilation support. Decorator syntax works at runtime only if a transpiler emits the calls MobX expects.
• The default enforceActions is 'observed' in MobX 6. Mutations outside an action throw when the state is observed. This is independent of decorator syntax.
• makeObservable and makeAutoObservable are the official first-class APIs for MobX 6. They accept annotations in the constructor and do not require decorator transpilation.

Likely explanation and trade-offs

Legacy decorator path keeps @observable/@action source code. It requires Babel legacy decorators plugin or TypeScript experimentalDecorators with legacy semantics. That adds build configuration, plugin ordering, and couples the codebase to a Stage-2 legacy mode that modern tooling is moving away from. The TC39 standard decorators have different semantics and are not compatible with MobX's decorator expectations.

makeObservable is a near-mechanical replacement: each decorator becomes an explicit entry in the annotations object passed in the constructor. Migration can be done store by store without a big bang. makeAutoObservable reduces boilerplate by inferring annotations, but inference can be wrong for edge cases and it does not handle class hierarchies well.

Bundle size impact is negligible for either path. The real cost is maintenance: legacy transpilation defers tooling risk, makeObservable removes it.

Interaction with enforceActions and incremental migration

• Decorator strategy does not change enforceActions behavior. The default 'observed' will surface untracked mutations regardless of syntax.
• Migrate a store, then audit mutations. Wrap stray mutations in action/runInAction or mark them explicitly.
• A hybrid is viable during transition: keep legacy decorator config for untouched stores while converting actively developed stores to makeObservable.

Minimal steps for this case

1. Confirm current decorator mode. Check tsconfig for experimentalDecorators and whether the new standard decorators mode is enabled. Verify Babel plugin order for legacy decorators.
2. Pick a pilot store. Convert @observable/@action fields to constructor annotations with makeObservable.
3. Run existing tests plus a reaction/autorun smoke test to confirm observability and action wrapping are preserved.
4. Temporarily configure enforceActions: 'always' in a test branch to surface untracked mutations, then relax to 'observed' once the store is clean.
5. Repeat per store. Remove legacy decorator plugins once all stores are migrated.

Assumption: you are on MobX 6 with enforceActions defaulting to 'observed'. Uncertainty remains around your exact TypeScript/Babel decorator mode, which changes feasibility of keeping legacy transpilation.

One missing diagnostic that changes the recommendation: which decorator mode is currently emitted by your toolchain — TypeScript experimentalDecorators legacy mode vs the new TC39 standard decorators mode. If you are already on standard decorators, legacy decorator syntax will break and migration is mandatory.