zodern:types

v1.0.9Published 2 months ago

zodern:types

Tooling to use Typescript types from Meteor packages in your apps.

Meteor Apps

For Meteor apps, zodern:types allows typescript to find the types from Meteor packages. Supports apps using Meteor 2.3 or newer.

To get started:

  1. Add zodern:types to your app by running:
meteor add zodern:types
  1. Configure typescript to find the types from packages. In your tsconfig.json file, add an entry to the compilerOptions.paths option and enable the preserveSymlinks option:
1{
2  "compilerOptions": {
3    "preserveSymlinks": true,
4    "paths": {
5      "meteor/*": [
6        "node_modules/@types/meteor/*",
7        ".meteor/local/types/packages.d.ts"
8      ]
9    }
10  }
11}

zodern:types stores the type definitions from packages in your app's .meteor/local/types folder. If your tsconfig has exclude configured, make sure the exclude rules do not exclude .meteor/local/types.

The preserveSymlinks option is needed so the type definitions for Meteor packages can use types from npm packages.

  1. Generate types

zodern:types is implemented as a Meteor linter plugin. The type definitions are updated whenever your app is built. You can also update the types directly by running meteor lint.

Finding types in packages

zodern:types tries various ways to identify which file to tell typescript to use for the package's types. It uses the first one that works:

  1. If the package is a local package, and only has a single ts file used as the main module, it uses this file
  2. If the package uses zodern:types:
    1. If a local package, the path from the typesEntry option in the package's package-types.json file is used
    2. Otherwise, uses the types that were generated when the package was published
  3. If the package has a single .d.ts file, this file is used
  4. If the package has a single file used as the main module, a file with the same name and the .d.ts extension is used. If the file is in a src folder, it will also check in a lib folder for the .d.ts file.

Meteor Packages

For Meteor packages, zodern:types makes it easier to publish a package with types.

Requires Meteor 2.3 or newer when running meteor publish. Outside of publishing (using in an app or running package tests), it is compatible with Meteor 1.4 and newer.

When publishing your package, it handles:

  • Ensuring Meteor includes any .d.ts and package-types.json files
  • Generate .d.ts files
  • Uninstall any npm dev dependencies, and re-install them after the package is published

In the future, it will also allow typescript to find the types of any of your package's dependencies, similar to what it does for Meteor apps.

To use:

  1. Add zodern:types as a dependency of your package in package.js:
1Package.onUse(function (api) {
2  api.use('zodern:types');
3});
  1. Add a package-types.json file:
1{
2  "typesEntry": "main.ts"
3}

While Meteor allows you to have separate main modules for each arch, Typescript only supports having a single set of types for the package. typesEntry should be the path to a ts file that exports the api and types that code using the package should have available. This could be the package's main module, or another ts file.

In development, typescript will use the ts file directly for the package's types. This way, the types will be automatically updated whenever Meteor rebuilds the package. When publishing, zodern:types will have typescript create .d.ts files.

Alternatively, typesEntry can point to a .d.ts file. In this case, that file will be used as is in both development and when publishing, and zodern:types won't generate any types when publishing. This is useful if your package isn't written in typescript (for example, your package supports older versions of Meteor that don't have the typescript package) and you manually create the .d.ts file, or you have a custom process for generating the type definitions.