Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zodern/meteor-types

Tooling to use types from Meteor packages
https://github.com/zodern/meteor-types

Last synced: 11 days ago
JSON representation

Tooling to use types from Meteor packages

Awesome Lists containing this project

README 

        
## 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:



```bash

meteor add zodern:types

```



2) 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:



```json

{

  "compilerOptions": {

    "preserveSymlinks": true,

    "paths": {

      "meteor/*": [

        "node_modules/@types/meteor/*",

        ".meteor/local/types/packages.d.ts"

      ]

    }

  }

}

```



`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. 



3) 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`:



```js

Package.onUse(function (api) {

  api.use('zodern:types');

});

```



2. Add a `package-types.json` file:



```json

{

  "typesEntry": "main.ts"

}

```



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.