Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix ESM/CJS compatibility #1

Merged
merged 3 commits into from
Feb 29, 2024
Merged

Fix ESM/CJS compatibility #1

merged 3 commits into from
Feb 29, 2024

Commits on Feb 9, 2024

  1. Fix ESM/CJS compatibility

    Superstruct cannot be imported in a TypeScript project that uses a
    `moduleResolution` of `node16` or `nodenext`. Any attempt to do so will result
    in type errors such as the following:
    
    ```
    node_modules/superstruct/dist/index.d.ts:1:15 - error TS2834: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Consider adding an extension to the import path.
    
    1 export * from './error';
                    ~~~~~~~~~
    
    node_modules/superstruct/dist/index.d.ts:2:15 - error TS2834: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Consider adding an extension to the import path.
    
    2 export * from './struct';
                    ~~~~~~~~~~
    
    node_modules/superstruct/dist/index.d.ts:3:15 - error TS2834: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Consider adding an extension to the import path.
    
    3 export * from './structs/coercions';
                    ~~~~~~~~~~~~~~~~~~~~~
    
    ...
    ```
    
    This is happening because although Superstruct is defined as an ESM library —
    the `module` field in `package.json` is set to `true` — its published TypeScript
    declaration files aren't ESM-compatible. This is due to the fact that imports
    are missing extensions, which is a requirement for ESM.
    
    At the same time, although Rollup is supposedly configured to emit both ESM- and
    CJS-compatible files, TypeScript does not know how to use the CJS variants. The
    `exports` field is the way to instruct TypeScript on how to do this, but
    `package.json` is missing this field. This makes it impossible to use
    Superstruct in a non-ESM library.
    
    This commit fixes both of these issues by making the following changes:
    
    - All imports in TypeScript files now use an extension of `.js`. This may seem
      like an odd choice, as there are no JavaScript files in the `src/` directory,
      but TypeScript doesn't resolve a module by trying to find a file with the
      given extension; it tries to find a declaration file that maps to the module
      path, based on a set of rules. Therefore, the file extension is really just a
      formality. In the end, Rollup is consolidating implementation files into one,
      so all of the imports will go away.
    - Type declaration files have been split into ESM and CJS variants. Since Rollup
      generates ESM variants with an `.mjs` extension and CJS variants with a `.cjs`
      extension, imports in declaration files also use either `.mjs` or `.cjs`
      depending on the variant.
    - `package.json` now has an `exports` field which instructs TypeScript how to
      resolve modules from either an ESM or CJS perspective.
    
    In addition, the tests have been updated to use Vitest instead of Babel so that
    they can read directly from the TypeScript configuration instead of having to
    use an explicit transform step.
    
    In conjunction with this change, the minimum Node version has been bumped to
    16.x and the GitHub workflows have been updated to stop testing on Node 14.x.
    14.x has reached EOL, the version of Vitest we're using isn't compatible with
    this version, and a `target` of `esnext` is being used in the TypeScript config,
    which require a JavaScript runtime that supports newer ES features such as
    `??=`, so the minimum Node version is effectively 16.x anyway.
    
    This commit is derived from the following PR on the Superstruct repo:
    <ianstormtaylor#1211>
    
    For more information on how TypeScript resolves modules, the "Modules Reference"
    section of the TypeScript handbook is quite helpful, and in particular these
    sections:
    
    - <https://www.typescriptlang.org/docs/handbook/modules/theory.html#the-role-of-declaration-files>
    - <https://www.typescriptlang.org/docs/handbook/modules/reference.html#node16-nodenext>
    mcmire committed Feb 9, 2024
    Configuration menu
    Copy the full SHA
    4e10994 View commit details
    Browse the repository at this point in the history

Commits on Feb 23, 2024

  1. Configuration menu
    Copy the full SHA
    9ee70b4 View commit details
    Browse the repository at this point in the history
  2. Remove logging

    mcmire committed Feb 23, 2024
    Configuration menu
    Copy the full SHA
    cbc26fb View commit details
    Browse the repository at this point in the history