Skip to content

Latest commit

 

History

History
70 lines (47 loc) · 3.7 KB

CONTRIBUTING.md

File metadata and controls

70 lines (47 loc) · 3.7 KB
Raw

Making a new release

Write release notes in README.md. Then,

npm version <major|minor|patch>
git push --follow-tags
npm publish

Enjoy life ❤️ 🌹

Debugging

Debug logging is enabled using the built in node util. We setup the log function as

var log = require('util').debuglog(require('./package').name);

If you want this function to actually do something just set the environment variable NODE_DEBUG=tsify e.g.

NODE_DEBUG=tsify browserify ... etc.

Internals and processing flow

tsify is a implemented as a Browserify plugin - not as a transform - because it needs access to the Browserify bundler - which is passed to plugins, but not to transforms. Access to the bundler is required so that tsify can include the TypeScript extensions in the _extensions array used by Browserify when resolving modules and so that tsify can listen to events associated with the Browserify pipeline. That's not possible with a transform, as a transform receives only a file path and a stream of content.

However, tsify does implement a transform that is wired up internally.

index.js - the plugin

  • It wires up internal transform.
  • It wires up the file and reset events. (Note that the file is informational nicety; it's not a core part of the Browserify process.)
  • It places .ts(x) extensions at the head of Browserify's extensions array.
  • It gathers the Browserify entry point files.

lib/Tsifier.js - the transform

  • The Tsifer is a Browserify transform.
  • It returns compiled content to Browserify.
  • It parses the tsconfig.json for options and files.
  • It configures the TypeScipt rootDir and outDir options to use an imaginary /__tsify__ directory.
  • It creates the Host, passing it to the TypeScript Compiler API to compile the program and check the syntax, semantics and output.

lib/Host.js - the TypeScript host

  • The Host is a TypeScript Compiler API host.
  • It abstracts the reading and writing of files, etc.
  • It parses and caches the parsed source files, reading them from disk.
  • It caches the compiled files when the TypeScript Compiler API writes compiled content.

Processing flow

  • When Browserify's pipeline is prepared, the initial list of files to be compiled is obtained from the tsconfig.json and from the Browserify entry points.
  • With the pipeline prepared, Browserify starts processing its entry points, passing their content through the Tsifier transform.
  • To obtain the transformed content, the Tsifier transform looks in a cache for the compiled content.
  • If the cache look up results in a miss, the transformed file is added to the list of files (if it's missing from the list) and a compilation of the list of files is performed.
  • Note that with TypeScript using the same module resolution mechanism as Browserify ("moduleResolution": "node") only a single compilation is required.
  • Browserify then locates any require calls in the transformed content and passes the content for these dependencies through the Tsifier transform.
  • This continues until all dependencies have been processed.

Caveats

  • The Host reads the source from disk; the content passed into the Tsifier transform is ignored. That means that any transforms added before the tsify plugin will be ineffectual.
  • If grunt-browserify is used, declarative configurations will see transforms will be loaded before plugins. To avoid that, an imperative configuration that uses the configure function would be necessary.