@fictjs/babel-preset

Babel preset for Fict - includes TypeScript, JSX, and Fict compiler

Deprecated: 0.30.1 is the final supported release of this preset and the in-tree legacy compiler. Fict 1.0.0 removes both. Migrate Vite applications to @fictjs/vite-plugin (Rust is the default), Webpack applications to @fictjs/webpack-plugin, or direct transforms to @fictjs/compiler. This preset remains functional in 0.30.1 for whole-build rollback, but it never bridges Rust output through a Babel visitor and must not be mixed with native output in one build. After 1.0.0, pin the complete application dependency set to 0.30.1 if legacy rollback is required.

Usage

npm install fict
npm install -D @fictjs/babel-preset
# or
yarn add fict
yarn add -D @fictjs/babel-preset

You can visit Fict for more documentation.

For standard apps, fict is the runtime dependency that pairs with this preset. Direct @fictjs/runtime usage remains supported for lower-level integrations, but your source imports should stay on one package family.

Configuration

@fictjs/babel-preset includes:

• @babel/plugin-transform-typescript (enabled by default and ordered before Fict)
• @babel/plugin-syntax-jsx
• @fictjs/compiler

All compiler options are forwarded through this preset. Fict and TypeScript lowering run in an isolated prepass, so sibling CommonJS or JSX transforms receive the compiled Fict AST instead of consuming macros or JSX first. Plugins and presets explicitly configured alongside this preset continue to participate in the outer Babel pipeline. The preset parses and preserves decorators but does not lower them. With no explicit parser profile, it accepts the current 2023-11 grammar (including auto-accessors and decorators on either side of export) plus a narrow compatibility exception for legacy parameter decorators. Other parser errors are still reported. An explicit decorator parser/transform plugin remains fully authoritative, and the syntax bridge does not claim Babel's parser override hook, so another plugin may provide one.

// babel.config.js
module.exports = {
  presets: [
    [
      '@fictjs/babel-preset',
      {
        // Preset-level options
        typescript: true,
        typescriptOptions: {
          // Optional: force every matched file into one parsing mode.
          // By default .ts/.tsx/.mts/.cts are detected from the filename.
          isTSX: true,
          allExtensions: true,
          allowNamespaces: true,
          allowDeclareFields: true,
          onlyRemoveTypeImports: false,
          optimizeConstEnums: false,
          jsxPragma: 'React.createElement',
          jsxPragmaFrag: 'React.Fragment',
          disallowAmbiguousJSXLike: false,
          rewriteImportExtensions: false,
        },
        // Compiler options (forwarded)
        strictGuarantee: true,
        emitModuleMetadata: 'auto',
      },
    ],
  ],
}

Recommended profiles:

// Strict default app/CI profile
module.exports = {
  presets: [['@fictjs/babel-preset', { strictGuarantee: true }]],
}

// Non-production migration / benchmark profile
module.exports = {
  presets: [
    ['@fictjs/babel-preset', { strictGuarantee: false, emitModuleMetadata: false, dev: false }],
  ],
}

Key defaults:

• compiler strictGuarantee: true
• production compilation (NODE_ENV=production) force-enables compiler strictGuarantee
• compiler emitModuleMetadata: 'auto'
• preset typescript: true
• preset typescriptOptions.allExtensions: false (detect from filename)
• preset typescriptOptions.allowDeclareFields: true

Cross-file hook metadata

When no explicit moduleMetadata or resolveModuleMetadata integration is configured, the preset prepares metadata for local filesystem imports before compiling their importer. Each Babel transform uses an isolated graph session, so importer-first builds and changed transitive hook dependencies cannot reuse metadata from an earlier transform. Dependency preparation uses the same TypeScript/CTS options as the importing transform.

Resource imports with a query stay opaque; URL-fragment imports resolve metadata from their base module. In strict guarantee mode, an imported hook-like function fails with FICT-H003 when current metadata cannot be obtained (for example, an unresolved alias or re-export, an unpublished package metadata entry, or a module cycle). Configure an explicit metadata store/resolver, publish package metadata, or use the Vite/Webpack graph integration for those module graphs. Non-strict migration builds emit the diagnostic as a warning and retain the opaque value behavior.

For .cts files, import name = require('source') and export = value are exposed to Fict analysis as a default import/export, then restored to native CommonJS output. This preserves hook metadata across importer-first CTS graphs without changing require() or module.exports runtime semantics.