https://github.com/GoogleFeud/ts-macros
A typescript transformer / plugin that allows you to write macros for typescript!
https://github.com/GoogleFeud/ts-macros
hacktoberfest macros typescript
Last synced: about 1 year ago
JSON representation
A typescript transformer / plugin that allows you to write macros for typescript!
- Host: GitHub
- URL: https://github.com/GoogleFeud/ts-macros
- Owner: GoogleFeud
- License: mit
- Created: 2021-07-09T06:13:01.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-24T12:23:21.000Z (over 1 year ago)
- Last Synced: 2025-04-12T22:03:44.704Z (about 1 year ago)
- Topics: hacktoberfest, macros, typescript
- Language: TypeScript
- Homepage: https://googlefeud.github.io/ts-macros/
- Size: 7.69 MB
- Stars: 374
- Watchers: 3
- Forks: 11
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ts-macros
ts-macros is a typescript transformer which allows you to create function macros that expand to javascript code during the transpilation phase of your program.
📖 **[Documentation](https://github.com/GoogleFeud/ts-macros/wiki)**
🎮 **[Playground](https://googlefeud.github.io/ts-macros/)**
✍️ **[Examples](https://github.com/GoogleFeud/ts-macros/wiki/Practical-Macro-Examples)**
## The Basics
All macro names must start with a dollar sign (`$`) and must be declared using the function keyword. Macros can then be called just like a normal function, but with a `!` after it's name: `$macro!(params)`. All the code inside of the macro is going to "expand" where the macro is called.
**What you can do with ts-macros**:
- Generate repetitive code
- Generate code conditionally, based on enviourment variables or other configuration files
- Generate types which you can use in your code (read more [here](https://github.com/GoogleFeud/ts-macros/wiki/Type-Resolver-Transformer))
- Create abstractions without the runtime cost
## Usage
```
npm i --save-dev ts-macros
```
Usage with ts-patch
```
npm i --save-dev ts-patch
```
and add the ts-macros transformer to your tsconfig.json:
```json
"compilerOptions": {
//... other options
"plugins": [
{ "transform": "ts-macros" }
]
}
```
Afterwards you can either:
- Transpile your code using the `tspc` command that ts-patch provides.
- Patch the instance of typescript that's in your `node_modules` folder with the `ts-patch install` command and then use the `tsc` command to transpile your code.
Usage with ts-loader
```js
const TsMacros = require("ts-macros").default;
options: {
getCustomTransformers: program => {
before: [TsMacros(program)]
}
}
```
Usage with ts-node
To use transformers with ts-node, you'll have to change the compiler in the `tsconfig.json`:
```
npm i --save-dev ts-node
```
```json
"ts-node": {
"compiler": "ts-patch/compiler"
},
"compilerOptions": {
"plugins": [
{ "transform": "ts-macros" }
]
}
```
CLI Usage (esbuild, vite, watchers)
If you want to use ts-macros with:
- tools that don't support typescript
- tools that aren't written in javascript and therefore cannot run typescript transformers (tools that use swc, for example)
- any tools' watch mode (webpack, vite, esbuild, etc)
you can use the CLI - [read more about the CLI and example here](https://github.com/GoogleFeud/ts-macros/wiki/CLI-usage)
## Security
This library has 2 built-in macros (`$raw` and `$comptime`) which execute arbitrary code during transpile time. The code is **not** sandboxed in any way and has access to your file system and all node modules.
If you're transpiling an untrusted codebase which uses this library, make sure to set the `noComptime` option to `true`. Enabling it will replace all calls to these macros with `null` without executing the code inside them. It's always best to review all call sites to `$$raw` and `$$comptime` yourself before transpiling any untrusted codebases.
**ttypescript/ts-patch:**
```json
"plugins": [
{ "transform": "ts-macros", "noComptime": true }
]
```
**manually creating the factory:**
```js
TsMacros(program, { noComptime: true });
```
## Contributing
`ts-macros` is being maintained by a single person. Contributions are welcome and appreciated. Feel free to open an issue or create a pull request at https://github.com/GoogleFeud/ts-macros.