ts-transformer-inline-file/README.md

A TypeScript custom transformer for inlining files

This is a TypeScript AST transformer [1] that allows you to include
content of a file into the transpiled code, i.e. *inline it* in
build-time.

You can think about it as a C preprocessor’s directive `#include` but
more powerful… way more powerful. If the referenced file is a JSON file,
it doesn’t include it as a string but converts the JSON to an object
literal. Thus it can be further optimized by a minifier. Moreover, if
you use an object destructing assignment, this transformer will optimize
it itself — include only the assigned properties!

Usage
=====

Add ts-transformer-inline-file package to your project as a
**dev**elopment dependency and [configure the
transformer](#_how_to_configure_the_transformer).

Inline Any Textual File
-----------------------

``` js
import { $INLINE_FILE } from 'ts-transformer-inline-file'

const words = $INLINE_FILE('../data/words.txt').trim().split(' ')
```

This will be transformed into:

``` js
const words = "lorem ipsum dolor\n".trim().split(' ');
```

…where `"lorem ipsum dolor\n"` is full content of the file
`../data/words.txt`.

Inline JSON Data
----------------

``` js
import { $INLINE_JSON } from 'ts-transformer-inline-file'

const pkg = $INLINE_JSON('../package.json')
```

This will be transformed into:

``` js
const pkg = { "name": "my-package", "version": "0.1.0", "license": "MIT", ... }
```

However, if you need only few properties from the referenced JSON file,
use object destructuring assignment:

``` js
const { name, version } = $INLINE_JSON('../package.json')
```

…and the transformer will include only the assigned properties:

``` js
const { name, version } = { "name": "my-package", "version": "0.1.0" }
```

> **Note**
>
> This works only for the top level; filtering of nested properties is
> currently not supported.

How to Configure the Transformer
================================

Unfortunately, TypeScript itself does not currently provide any easy way
to use custom transformers (see
[Microsoft/TypeScript\#14419](https://github.com/Microsoft/TypeScript/issues/14419)).
Fortunately, there are few solutions.

TTypescript
-----------

If you don’t use any bundler such as Rollup or webpack,
[TTypescript](https://github.com/cevek/ttypescript) is the way to go. It
provides wrappers `ttsc` and `ttserver` for the `tsc` and `tsserver`
commands that add support for custom transformers. All you have to do is
to use these wrappers instead of the original commands and define the
transformer in your `tsconfig.json`:

**tsconfig.json:.**

``` jsonc
{
  "compilerOptions": {
    // ...
    "plugins": [
      { "transform": "ts-transformer-inline-file/transformer" }
    ]
  },
  // ...
}
```

Rollup (with rollup-plugin-typescript2)
---------------------------------------

**rollup.config.js:.**

``` js
import typescript from 'rollup-plugin-typescript2'
import inlineFileTransformer from 'ts-transformer-inline-file/transformer'

export default {
  // ...
  plugins: [
    typescript({
      transformers: [
        (service) => ({
          before: [ inlineFileTransformer(service.getProgram()) ],
          after: [],
        }),
      ],
    }),
  ],
}
```

Webpack (with ts-loader or awesome-typescript-loader)
-----------------------------------------------------

**webpack.config.js:.**

``` js
const inlineFileTransformer = require('ts-transformer-inline-file/transformer').default

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.ts$/,
        loader: 'ts-loader', // or 'awesome-typescript-loader',
        options: {
          getCustomTransformers: (program) => ({
            before: [
              inlineFileTransformer(program),
            ],
          }),
        },
      },
    ],
  },
}
```

License
=======

This project is licensed under [MIT
License](http://opensource.org/licenses/MIT/). For the full text of the
license, see the [LICENSE](LICENSE) file.

[1] If you’ve never heard about TypeScript transformers, I can recommend
[this blog
post](https://blog.logrocket.com/using-typescript-transforms-to-enrich-runtime-code-3fd2863221ed/)
to dive into the topic.