{"id":16483546,"url":"https://github.com/trevorblades/remark-typescript","last_synced_at":"2025-03-21T07:30:54.250Z","repository":{"id":35021633,"uuid":"197478312","full_name":"trevorblades/remark-typescript","owner":"trevorblades","description":"👭 Transpiles TypeScript code blocks to JavaScript and inserts them into the page","archived":false,"fork":false,"pushed_at":"2023-01-08T12:21:08.000Z","size":1931,"stargazers_count":8,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T22:38:13.089Z","etag":null,"topics":["code","code-blocks","javascript","markdown","mdast","remark","remark-plugin","transform","transpile","typescript"],"latest_commit_sha":null,"homepage":"https://npm.im/remark-typescript","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trevorblades.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-17T23:45:40.000Z","updated_at":"2024-01-04T10:22:39.000Z","dependencies_parsed_at":"2023-01-15T12:15:25.782Z","dependency_job_id":null,"html_url":"https://github.com/trevorblades/remark-typescript","commit_stats":null,"previous_names":["trevorblades/gatsby-remark-typescript"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trevorblades%2Fremark-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trevorblades%2Fremark-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trevorblades%2Fremark-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trevorblades%2Fremark-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trevorblades","download_url":"https://codeload.github.com/trevorblades/remark-typescript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244757357,"owners_count":20505381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code","code-blocks","javascript","markdown","mdast","remark","remark-plugin","transform","transpile","typescript"],"created_at":"2024-10-11T13:14:22.142Z","updated_at":"2025-03-21T07:30:53.904Z","avatar_url":"https://github.com/trevorblades.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# remark-typescript\n\n[![Build Status](https://github.com/trevorblades/remark-typescript/workflows/Node%20CI/badge.svg)](https://github.com/trevorblades/remark-typescript/actions)\n\nA [remark](https://github.com/remarkjs/remark) plugin to transpile TypeScript code blocks.\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Gatsby example](#gatsby-example)\n- [API](#api)\n  - [remark().use(remarkTypescript[, options])](#remarkuseremarktypescript-options)\n- [Preserving unused imports](#preserving-unused-imports)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install remark-typescript\n```\n\n## Usage\n\n```js\nimport remark from 'remark';\nimport {remarkTypescript} from 'remark-typescript';\n\nremark()\n  .use(remarkTypescript)\n  .process(...);\n```\n\n### Gatsby example\n\n```js\n// gatsby-config.js\nconst {remarkTypescript} = require('remark-typescript');\n\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-plugin-mdx',\n      options: {\n        remarkPlugins: [remarkTypescript]\n      }\n    }\n  ]\n}\n```\n\n## API\n\n### `remark().use(remarkTypescript[, options])`\n\nTransform TypeScript code blocks to JavaScript and inserts them back into the page. Use `options` to affect the formatting or control which code blocks get transpiled.\n\n#### `options.prettierOptions`\n\nAn object of options supplied to `prettier.format` when formatting the JS output. See [Prettier's docs](https://prettier.io/docs/en/options) for more information.\n\n```js\nimport remark from 'remark';\nimport typescript from 'remark-typescript';\n\nremark()\n  .use(\n    typescript,\n    {\n      prettierOptions: {\n        semi: false,\n        singleQuote: false\n      }\n    }\n  )\n  .process(...);\n```\n\n#### `options.customTransformations`\n\nCustom transformations allow code and node manipulation to occur during the transpilation process. There are four code hook locations `beforeTranspile`, `afterTranspile`, `beforeFormat` and `afterFormat`. As well as one node manipulation callback that occurs after all text manipulation is complete.\n\n##### Transformer Structure\n\nCustom transformations take the following shape, note that every single property listed below is optional.\n\n```ts\n{\n  code: {\n    beforeTranspile: () =\u003e \"\",\n    afterTranspile: () =\u003e \"\",\n    beforeFormat: () =\u003e \"\",\n    afterFormat: () =\u003e \"\",\n  },\n  node: () =\u003e {},\n}\n```\n\n##### Code Transformer Signature\n\nThe code transformer functions all have the same signature, `(code: string, meta?: string) =\u003e string`. Code represents the source code at that point, and meta describes the meta string attached to the code block. Note, the meta string is optional. The decision to pass meta as a string as opposed to the node is that the intent is that nodes are immutable until the final node transformer. The returned string is then applied to the forward processes. \n\n##### Node Transformer Signature\n\nThe node transformer as the signature `(originalCodeNode, transpiledCodeNode): void` where all mutations of the nodes happens in place on the object, so no return type is required. Full access to all properties is available here, and certain tasks can be done like cleaning up meta tags.\n\n#### `options.filter`\n\nThe `filter` callback allows for fine-tuned selection of TypeScript blocks. By default, `remark-typescript` will visit *all* TypeScript code blocks in your site and insert the transformed and formatted JavaScript after each of them. This feature allows the author to choose which TypeScript code blocks to transform by returning `true` or `false`.\n\nTo keep migration easy, a helper function is included to return the `wrapperComponent` functionality.\n\n##### `isWrapped(options: {wrapperComponent: string})` MDX only\n\nThe `isWrapped` helper allows for easy filtering for code blocks only in a certain component. The option `wrapperComponent` is a string representing the name of the React component used to wrap code blocks that you wish to transform.\n\n```js\n// gatsby-config.js\nconst {remarkTypescript, isWrapped} = require('remark-typescript');\n\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-plugin-mdx',\n      options: {\n        remarkPlugins: [\n          [\n            remarkTypescript,\n            {\n              // configure the JSX component that the plugin should check for\n              filter: isWrapped({wrapperComponent: 'CodeBlockWrapper'})\n            }\n          ]\n        ]\n      }\n    }\n  ]\n};\n```\n\nIn your MDX file, surround code blocks that you want to be transformed with their own pair of opening and closing JSX tags. The name of the component that you use here must match the `wrapperComponent` option that you passed along to this plugin.\n\n````jsx\nimport {CodeBlockWrapper} from '../components';\n\n\u003cCodeBlockWrapper\u003e\n\n```ts\n// this code block will be transformed\n```\n\n\u003c/CodeBlockWrapper\u003e\n\n```ts\n// this one will be ignored\n```\n````\n\nYour wrapper component could include some additional logic, like allowing users to switch between the original and transformed code blocks. Check out Apollo's [`MultiCodeBlock` component](https://github.com/apollographql/gatsby-theme-apollo/blob/master/packages/gatsby-theme-apollo-docs/src/components/multi-code-block.js) for an example of how to accomplish this.\n\n![Example wrapper component](./example.gif)\n\n#### `options.throwOnError`\n\nSet `throwOnError` to `true` to throw when the transpilation step results in an error. By default, errors will be logged to the console and will not cause your build to fail.\n\n## Preserving unused imports\n\nThis plugin uses [Babel](https://babeljs.io) to do the transpilation, and because of this, you might notice unused imports being removed from your transpiled JavaScript codeblocks. To avoid this behavior, you can use a `// preserve-line` directive on lines that you don't want to be removed from the transpiled version.\n\n````markdown\n```ts\nimport gql from 'graphql-tag';\nimport {ApolloClient} from 'apollo-client'; // preserve-line\n\nexport const typeDefs = gql`\n  type Query {\n    posts: [Post]\n  }\n`;\n```\n````\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrevorblades%2Fremark-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrevorblades%2Fremark-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrevorblades%2Fremark-typescript/lists"}