How to add extra replacers

[raouldeheer]

In this tutorial I will explain how to add an extra replacer to tsc-alias with command-line, API or tsconfig.json.
A replacer is a function that transform an import statement to a replaced import statement.
For example: import "@/functions" to import "./functions".

Replacer code

This is an example replacer that logs all import statements.

import { AliasReplacerArguments } from 'tsc-alias';

export default function exampleReplacer({
  orig,
  file,
  config
}: AliasReplacerArguments): string {
  console.log(orig);
  
  return orig;
}

Compiling replacer to commonjs

Replacers have to be compiled to commonjs. This can be done with this command:

tsc replacer.ts --module commonjs --target es2017

Adding replacer to tsc-alias

With command-line

tsc-alias -r ./exampleReplacer.js

================ OR ===================

tsc-alias -r ./exampleReplacer.js ./otherReplacer.js

With API

import { replaceTscAliasPaths } from 'tsc-alias';

replaceTscAliasPaths({
      replacers: ["./exampleReplacer.js", "./otherReplacer.js"]
});

With tsconfig (recommended)

{
  "compilerOptions": {
    // Normal compilerOptions...
  }
  "tsc-alias": {
    "replacers": {
      "myextra": {
        "enabled": true,
        "file": "./exampleReplacer.js"
      },
      "myextra2": {
        "enabled": true,
        "file": "./otherReplacer.js"
      }
    }
  }
}

[ThijmenDam]

I cannot seem to get this working. My code is nearly identical to yours, only changed .exampleReplacer.js to .ts as you included types in your first code snippet.

I get the following error: tsc-alias error: Failed to import replacer "./exampleReplacer.ts".

[ThijmenDam]

Thanks for the quick reply, this has resolved my issue.

[ThijmenDam]

Small issue: when using import { AliasReplacerArguments } from 'tsc-alias' I receive the following import error:

TS2305: Module '"tsc-alias"' has no exported member 'AliasReplacerArguments'.

It seems this type is not exported from tsp-alias/dist/index.d.ts.

[raouldeheer]

AliasReplacerArguments should be exported with the AliasReplacer type.

[ThijmenDam]

I see, since AliasReplacerArguments is a subtype of AliasReplacer. However, the import error still persists, as the type is not explicitly exported.

What does work, is the following:

import { AliasReplacer } from 'tsc-alias';

const exampleReplacer: AliasReplacer = (({ orig, file, config }) => {
  // ...
});

The arguments are now properly inherited from AliasReplacer, which is exported.

[raouldeheer]

I've opened pr #80 to fix this issue.

[muhammad-bin-zafar]

@raouldeheer You might want to update the example code snippet mentioned above in ESM format.

A replacer written in ESM format didn't work for me, got error "Failed to import replacer".
When changed to CommonJS, the replacer worked.

[raouldeheer]

Replacers are required to be in commonjs format. If you have a replacer in ESM try compiling it to commonjs with typescript (tsc) or babel.

[mauriver21]

It took me a whole day to figure out how to write a replacer for tsc-alias, so I will share a definitive solution:

If your package.json type is module, the replacer must be a .cjs file.

package.json file:

{
  "name": "your-project-name",
  "description": "",
  "type": "module",
  "files": [
    "dist"
  ],
  ...
}

Then, if you need to add a replacer, keeping the default tsc-alias replacer, you need to config the tsconfig.json as follows:

tsconfig.json file:

{
  "compilerOptions": {
     ...
  },
  "tsc-alias": {
    "verbose": true,
    "resolveFullPaths": true,
    "replacers": {
      "yourCustomReplacer": {
        "enabled": true,
        "file": "./yourCustomReplacer.cjs" //Your custom replacer, must be .cjs when package.json type is module.
      }
    }
  }
}

Finally, the yourCustomReplacer.cjs must be defined as follows:

const fs = require('fs');

exports.default = ({ orig, file }) => {
  const fileContents = fs.readFileSync(file, 'utf8');
  //Add your custom logic for replacing text inside the file.
  newContents = newContents.replace(/\.(png|jpg|gif|svg)";/g, '.jsx"');
  fs.writeFileSync(file, newContents);
  return orig;
};

[av-k]

I wonna to add one detail about the option tsc-alias.replacers.X.file.
During debugging the reason of why I getting "tsc-alias error: Failed to import replacer " error, I found out the next.
I had a config file in the directory "configs/ts.config.mjs.json" and it looks like:

{
  ...
  "tsc-alias": {
    "resolveFullPaths": true,
    "verbose": false,
    "replacers": {
      "hanldeDependencies": {
        "enabled": true,
        "file": "../scripts/treatExtensions.js"
      }
    }
  }
}

where "scripts/treatExtensions.js" is:

exports.default = (props) => {
  const { orig } = props;

  if (/mydep\/plugin\//.test(orig)) {
    const lastCharOfImportExpression = orig.substr(-1);
    const mainPartOfImportExpression = orig.substr(0, orig.length - 1);
    const updatedImportExpression = `${mainPartOfImportExpression}.js${lastCharOfImportExpression}`;

    return updatedImportExpression;
  }

  return orig;
};

File "scripts/treatExtensions.js" was called but the error "tsc-alias error: Failed to import replacer " appears all time.
The fix was rewrite the relative path
from:

"file": "../scripts/treatExtensions.js"

to:

"file": "scripts/treatExtensions.js"

Which is strange, since the file is always processed anyway and all other configuration files are specified with relative paths...