Setup & Configuration

Setting up your project to use atom-ts-transpiler is very simple and can be done within a matter of minutes. Just write your package as you normally would (using .ts and/or .tsx extensions on your source files,) then follow these steps to get it running in Atom:

1. Add atom-ts-transpiler and typescript to your package.json as dependencies or do npm install --save atom-ts-transpiler typescript from the command line. Any version of TypeScript since 1.6 should be compatible, so feel free to specify whatever version range is appropriate for your package. Note that atom-ts-transpiler relies on features introduced in TypeScript 1.6, so older versions will definitely not work.
2. Optionally, make sure that your package has a tsconfig.json file, and that it builds properly with tsc --project . on the command-line. Alternatively, you can specify compiler options in your package.json instead (see below,) but having a tsconfig is highly recommended. If you have more than one tsconfig file, each source file will be compiled using the options from the "nearest" one, considering the containing directory and its direct ancestors.
3. Finally, tell Atom to use the transpiler by adding an atomTranspilers property to your package.json file, like so:

{
  "name": "my-super-duper-package",
  "version": "2.1.4",
  // ...
  "atomTranspilers": [
    {
      "transpiler": "atom-ts-transpiler",
      "glob": "{!(node_modules)/**/,}*.ts?(x)",
      "options": {
        "compilerOptions": { },
        "cacheKeyFiles": [],
        "verbose": false
      }
    }
  ]
}

Now, any time Atom is asked to require a file within the package directory whose relative path matches the glob, and there is not already a valid cached version of the compilation output, the transpiler will be asked to handle transpilation and return JavaScript code.

The atomTranspilers Listing

Properly specifying the transpiler options for your package is fairly straightforward, but it's worth noting that mistakes can adversely affect load times or even cause the package not to work at all. Each listing in the atomTranspilers array takes the following form:

Property	Type	Description
transpiler	string	The name of the package which will handle transpilation of files matching glob.
glob	string	A minimatch-style glob specifying which files this transpiler should be responsible for transpiling. For most TypeScript packages, the catch-all glob {!(node_modules)/**/,}*.ts?(x) should be appropriate (this corresponds to all .ts and .tsx files within the package directory except those inside the top-level node_modules folder). If you for some reason need to tweak this glob to include other paths, globtester.com is a nice utility to help ensure that your glob is still hitting the correct files.
options	object or undefined	An object containing configuration options specific to the associated transpiler. (See below for the options for atom-ts-transpiler.)

The top-level properties listed above are used by the Atom core, and are the same regardless of which transpiler package you are using. The properties within the options object, listed below, are specific to atom-ts-transpiler and may differ for other transpiler packages.

Property	Type	Description
.compilerOptions	object or undefined	A record of TypeScript compiler options, identical to the compilerOptions property available within tsconfig files. Options specified here will apply to all files in the project, overriding those specified in the project's tsconfig.json file.
.cacheKeyFiles	string[] or undefined	A list of file paths relative to the package's root directory which are considered critical to the compile cache's validity. If any of the files listed here are changed or updated, all of the cached files generated with this transpiler will be considered stale and re-transpiled the next time they are required. This typically means files that affect the build output but aren't required at runtime. Note that the each source file's associated tsconfig will automatically be included in the cache key and doesn't need to be manually specified here. For more information on cache keys and how they are used internally, see Atom: Compile Cache.
.verbose	boolean or undefined	When set to true, will output debugging text to the Developer Console (Ctrl+Shift+I) each time a file's transpilation is requested. This can be useful for debugging your project, but it's not recommended that you distribute a package with this option enabled.