edemaine:civet

Civet in Meteor

This Meteor package lets you write code in Civet in .civet files, and automatically compiles them to JavaScript.

For context:

• Civet is a modern successor to CoffeeScript that is roughly a superset of TypeScript, plus many other features and syntax, and which compiles to TypeScript/JavaScript.
• Meteor is an (aging) full-stack JavaScript framework with powerful real-time data synchronization. I use it to build Cosuite.

Installation

meteor add edemaine:civet
meteor npm install --save-dev @danielx/civet

Note that the Civet compiler @danielx/civet is a peer NPM dependency, so that you can control which version to install. But that means you need to install it yourself.

This package offers broad compatibility with Meteor versions 2 and 3. In particular, for older Meteor releases that ship an older Node.js, Babel transpiles the Civet compiler itself, so that it runs despite modern JavaScript syntax.

Example

For an example Meteor app using Civet, see meteor-civet-test-react.

Details

• Enables comptime blocks
• Compiles Civet to TypeScript, letting Meteor handle transpilation to JavaScript. This should support all TypeScript features.

Babel Customization Protocol

edemaine:civet supports a lightweight protocol for Meteor compiler plugins to customize the use of BabelCompiler. For example, edemaine:solid uses this protocol to conditionally switch from React to Solid JSX transforms. In particular, this allows edemaine:civet and edemaine:solid to be used together to support .civet files with Solid JSX.

The protocol is defined by two optional properties on Meteor:

• globalThis.babelFeatures: object merged into the extraFeatures first argument passed to new BabelCompiler(...)
• globalThis.modifyBabelConfig(babelOptions, inputFile): callback for mutating Babel options on a per-file basis

See further details.

References

This implementation is based on Meteor's CoffeeScript compiler, which is MIT licensed:

• https://github.com/meteor/meteor/blob/devel/packages/non-core/coffeescript-compiler/coffeescript-compiler.js
• https://github.com/meteor/meteor/blob/devel/packages/non-core/coffeescript/compile-coffeescript.js

Testing

npm install
meteor test-packages ./

Troubleshooting

If you're having weird compilation issues (particularly during development, or perhaps when upgrading edemaine:civet), clear the cache and restart Meteor:

rm -rf .meteor/local/plugin-cache/edemaine_civet

Release Process

This package publishes two release tracks:

• v0.x.x releases are for Meteor 2
• v1.x.x releases are for Meteor 3

Release workflow:

1. Increment both version tracks in package.js.
2. git commit -a
3. npm run publish, or separately:
   • npm run publish:2 to release for Meteor 2
   • npm run publish:3 to release for Meteor 3

Future Work

Ideally we would integrate more with Meteor's TypeScript support, such as zodern:types.