atom-ts-transpiler

This package provides a simple, easily-configured compatibility layer that sits between Atom and the TypeScript compiler, giving Atom the ability to run packages written and distributed entirely in TypeScript. It's small (<25 KB including documentation,) supports any version of TypeScript since 1.6, and can be set up within minutes. It even respects the compiler options specified in your tsconfig.json file automatically, without the need for any additional configuration.

This project was inspired by the GitHub team's atom-babel6-transpiler, and utilizes the same interface to provide Atom with the ability to transpile TypeScript code on-demand. Special thanks go to them, as well as the other Atom users and community members who helped see this project through to a stable release.

About

Setup & Configuration

Setting up your project to use atom-ts-transpiler is extremely simple. Just write your package in TypeScript, then follow these steps to get it running in Atom:

1. Add atom-ts-transpiler and typescript to your package.json as dependencies (not devDependencies) 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. 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 use the closest one, starting with the directory it's in and considering only direct ancestors.
3. Finally, tell Atom about 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
      }
    }
  ]
}

And that's it! Now, any time a file matching glob is loaded or required at runtime, Atom will first pass it through the TypeScript transpiler, caching the result until your package is updated or one of the cacheKeyFiles changes. It's that easy!

Peer Dependencies

Required Peer Dependencies

• typescript: Any version 1.6 or later should be compatible, but versions older than 1.6 definitely will not work. Use whichever version you need in order for your package to compile properly (although, of course, more recent versions are usually preferable.)

Recommended Peer Dependencies

• @types/atom: TypeScript definitions for the Atom API, maintained as part of the DefinitelyTyped project. You'll almost certainly need this unless you're getting your typedefs from somewhere else.

Optional "Peer Dev Dependencies"

None of these are strictly necessary, but you may find some or all of them useful in developing your package. If you know of any other packages you think you should be listed here, let us know!

• atom-transpiler-debug-tool: A convenient script for inspecting the state of the Atom compile cache, which can help isolate issues in projects that use custom transpilers.
• atom-mocha-test-runner: An alternate test runner for Atom packages, which (with some tinkering) can be configured to run tests written in TypeScript.
• @types/atom-mocha-test-runner: Additional type definitions for atom-mocha-test-runner.

Example Projects

The examples directory of the GitHub repo contains a bare-bones example of what a new package setup might look like, if you're looking for somewhere to get started. If you want to see how people are using atom-ts-transpiler in their own packages, check out one of these!

• ide-powershell: A package for Atom providing rich PowerShell language features via Atom IDE!
• path-of-exile-item-filter: An Atom package designed to make editing Path of Exile item filters easier.

If you'd like to see your package listed here to help out newcomers to the Atom/TypeScript modding community, we'd love to hear from you! Just open an issue on GitHub with a link to its Atom package directory page and a brief description of what it does, and we'll add you here in the next patch version. 😊

License

The source code of this project is released under the MIT Expat License, which freely permits reuse and redistribution. Feel free to use and/or modify it in any way, provided that you include the copyright notice and terms of this license with any copies that you make.

The contents of the examples directory are not subject to the following license, and are freely released into the public domain by their respective authors. These examples are provided as-is with no warranty of any kind, and under no circumstances shall the author(s) be held liable for damages resulting directly or indirectly from their use.

Copyright © 2017 "smhxx" (https://github.com/smhxx)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.