README.adoc

TypeScript 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 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').trim().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 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:

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),
            ],
          }),
        },
      },
    ],
  },
}

Development

System Requirements

• NodeJS 14+

• Pandoc and Asciidoctor (used only for converting README.adoc to Markdown for npmjs)

Used Tools

• TypeScript the language

• yarn for dependencies management and building

• ESLint for linting JS/TypeScript code

• tape for testing

How to Start

1. Clone this repository:

   git clone https://github.com/jirutka/ts-transformer-inline-file.git
   cd ts-transformer-inline-file

2. Install Yarn (if you don’t have it already):

   npm install -g yarn

3. Install all JS dependencies:

   yarn install

4. Build the project:

   yarn build

5. Run tests:

   yarn test

6. Run linter:

   yarn lint

Visual Studio Code

If you use Visual Studio Code, you may find the following extensions useful:

• EditorConfig for VS Code

• ESLint

• yarn

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.