Typescript transformer for asset imports
npm install ts-transform-asset
This transformer will simply convert imports or reexports like:
``typescript`
import foo from './images/foo.gif'
import * as bar from '../images/bar.png'
export { default } from './foobar.svg'
export { default as foobar } from './foobar.ico'
to:
`typescript`
const foo = 'assets/foo.gif'
const bar = 'assets/bar.png'
const foobar_svg_1 = 'assets/foobar.svg'
export default foobar_svg_1
export const foobar = 'assets/foobar.ico'
Documents, messages, code (including variable names and comments), are in English.
Anyway, because Slune is French firm, all documents and important messages must also be provided in French. Other translations are welcome.
:fr: Une version française de ce document se trouve ici.
Installation is done using npm install command:
`bash`
$ npm install --save-dev ts-transform-asset
You have a project using Webpack with the file-loader plugin. When this plugin finds an import foo from "./images/foo.gif", it copies foo.gif to an assets directory and change the usage of foo using the public path to the file. Great.
Then, you have another project, which contains the web server. This server, which depends on the previous project, will take the bundle and all assets to serve them to the clients. But you also want to do some server side rendering (SSR). And for this, you cannot use the bundle created by Webpack because it does not have an appropriate entry point for the server (e.g. you need to use a StaticRouter instead of a BrowserRouter). Or maybe you prefer using the transpiled javascript and definition files instead of the minified and untyped bundle.
Unfortunately, this is not working, because your server do not know what to do with your assets files.
Using this transformer to transpile the web pages (not for Webpack!), you will convert your imports into constants with the URL of where resources should be found, and dependents project will be able to work without any more configuration.
The transformer accepts the following parameters:
- assetsMatch: a regular expression used to select asset imports, e.g., for all .png files, assetsMatch = "\\.png$". This parameter is mandatory.targetName
- : a template similar to Webpack file-loader name used to convert the name of the asset. If you defined a publicPath in the output parameter of Webpack, then you will probably need to specify this path here too. This parameter is optional and defaults to [hash].[ext].
There is currently no way of declaring a transformer in the vanilla _TypeScript_ compiler. If you do not want to write your own compiler using the typescript API, you can use the ttypescript wrapper.
Your TypeScript code should already be well written if you are using Webpack and the file-loader. If not, you can follow the instructions below.
Before using them, you need to declare the new module types, for example in an assets.d.ts file like this:
`typescript`
declare module '*.png' {
const content: string
export default content
}
Older versions of file-loader (before 5.0.2) where not using a default export. You should then declare module types this way in this case:
`typescript`
declare module '*.png' {
const content: string
export = content
}
When the (module) file is to be used:
`typescript
import image from './image.png'
const url: string = image
`
It is even possible to re-export the asset file:
`typescript`
export { default as image } from './image.png'
Then, in another file:
`typescript
import { image } from '../images'
const url: string = image
`
For older versions of file-loader (before 5.0.2), only namespace import is possible:
`typescript
import * as image from './image.png'
const url: string = image
`
For ttypescript, configure your tsconfig.json. Example:
`json`
{
"compilerOptions": {
"plugins": [
{
"transform": "ts-transform-asset",
"assetsMatch": "\\.png$",
"targetName": "assets/[name]-[hash].[ext]"
}
]
}
}
- The transformer will not detect nor modify any require statement. It is advised to run it in the before phase of the compilation, before the code is converted to an older version of ECMAScript.default
- The transformer either modify the code if it conforms to what is expected, or do not touch it at all. There is an exception anyway for the re-export declarations: if the source module matches the given parameters, but the exported property is not , then this export property will be removed.
Prior to version 3.x.x, there was a configuration entry targetPath which was the prefix used to add to the target asset name. Everything is now defined in the new targetName entry. Converting from previous to current configuration is as simple as the below example:
`diff`
"transform": "ts-transform-asset",
"assetsMatch": "\\.png$",
- "targetPath": "assets"
+ "targetName": "assets/[name].[ext]"
}
]
In addition to the previous modifications, note that prior to version 2.x.x, transformer was of type config. Since version 2.0.0, transformer is of type program, which is the default. If you are upgrading from an older version and using ttypescript, you have to update the plugin configuration in tsconfig.json:
`diff``
{
"transform": "ts-transform-asset",
- "type": "config",
"assetsMatch": "\\.png$",
"targetName": "assets/[name].[ext]"
Even though we cannot guarantee a response time, please feel free to file an issue if you have any question or problem using the package.
_Pull Requests_ are welcome. You can, of course, submit corrections or improvements for code, but do not hesitate to also improve documentation, even for small spell or grammar errors.