ts-transformer-inline-file

A TypeScript custom transformer for inlining files

Usage no npm install needed!

<script type="module">
  import tsTransformerInlineFile from 'https://cdn.skypack.dev/ts-transformer-inline-file';
</script>

README

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 development dependency and configure the transformer.

Inline Any Textual File

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

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

This will be transformed into:

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

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

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

This will be transformed into:

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:

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

…and the transformer will include only the assigned properties:

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). Fortunately, there are few solutions.

TTypescript

If you don’t use any bundler such as Rollup or webpack, 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:.

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

Rollup (with rollup-plugin-typescript2)

rollup.config.js:.

import typescript from 'rollup-plugin-typescript2'
import packageJsonTransformer from 'ts-transformer-inline-file/transformer'

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

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

webpack.config.js:.

const packageJsonTransformer = require('ts-transformer-inline-file/transformer').default

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

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.

[1] If you’ve never heard about TypeScript transformers, I can recommend this blog post to dive into the topic.