{"id":13602395,"url":"https://github.com/imjuni/ctix","last_synced_at":"2025-04-09T13:07:59.988Z","repository":{"id":38029702,"uuid":"285958654","full_name":"imjuni/ctix","owner":"imjuni","description":"CLI to generate barrel file for webpack, rollup entrypoint","archived":false,"fork":false,"pushed_at":"2024-04-13T16:13:49.000Z","size":2607,"stargazers_count":69,"open_issues_count":1,"forks_count":20,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-01T20:46:39.925Z","etag":null,"topics":["automation","barrel","barrel-files","barrels","cli","index","rollupjs","typescript","webpack"],"latest_commit_sha":null,"homepage":"","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/imjuni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["imjuni"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"custom":null}},"created_at":"2020-08-08T02:33:03.000Z","updated_at":"2024-08-21T08:40:12.015Z","dependencies_parsed_at":"2024-03-02T04:27:13.690Z","dependency_job_id":"4139b463-23de-47ce-ba19-59f0029da6e1","html_url":"https://github.com/imjuni/ctix","commit_stats":{"total_commits":90,"total_committers":5,"mean_commits":18.0,"dds":0.06666666666666665,"last_synced_commit":"e40dd84fa56941a65feb40ff4afab4cdaf46abec"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imjuni%2Fctix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imjuni%2Fctix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imjuni%2Fctix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imjuni%2Fctix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imjuni","download_url":"https://codeload.github.com/imjuni/ctix/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045232,"owners_count":21038553,"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":["automation","barrel","barrel-files","barrels","cli","index","rollupjs","typescript","webpack"],"created_at":"2024-08-01T18:01:22.092Z","updated_at":"2025-04-09T13:07:59.964Z","avatar_url":"https://github.com/imjuni.png","language":"TypeScript","funding_links":["https://github.com/sponsors/imjuni"],"categories":["cli"],"sub_categories":[],"readme":"# ctix - Next generation Create TypeScript barrel\n\n![ts](https://flat.badgen.net/badge/Built%20With/TypeScript/blue)\n[![Download Status](https://img.shields.io/npm/dw/ctix.svg)](https://npmcharts.com/compare/ctix?minimal=true)\n[![Github Star](https://img.shields.io/github/stars/imjuni/ctix.svg?style=popout)](https://github.com/imjuni/ctix)\n[![Github Issues](https://img.shields.io/github/issues-raw/imjuni/ctix.svg)](https://github.com/imjuni/ctix/issues)\n[![NPM version](https://img.shields.io/npm/v/ctix.svg)](https://www.npmjs.com/package/ctix)\n[![License](https://img.shields.io/npm/l/ctix.svg)](https://github.com/imjuni/ctix/blob/master/LICENSE)\n[![ci](https://github.com/imjuni/ctix/actions/workflows/ci.yml/badge.svg)](https://github.com/imjuni/ctix/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/imjuni/ctix/branch/master/graph/badge.svg?token=DADV7ss5bh)](https://codecov.io/gh/imjuni/ctix)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n\nentrypoint `barrel` file automatically generated cli tool\n\n## Why ctix?\n\nHave you ever developed a library project in the TypeScript language? Unlike API servers or desktop applications, library projects do not have executable scripts or functions. Therefore, it is common to organize a number of functions and variables to be included in the library in an `barrel` file. However, it is inconvenient to rewrite the `barrel` file every time you add a function or variable, and it is easy to make a mistake and miss a function or variable you intended. `ctix` uses the [TypeScript compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to automatically generate the `barrel` file by searching your TypeScript project for functions and variables with the export keyword added.\n\nTo summarize,\n\n1. automatically extracts statement with the export keyword applied\n1. generate a single `barrel` file or directory-specific `barrel` files\n1. automatically generate configuration files via interactive prompts\n1. automatically add type keyword to interface, type aliases to indicate they are pure types\n   - eg. `export { type IAmSuperHero } from './marvel';`\n1. can be set to exception files via comments in source code files (eslint style)\n1. always generates a compilable `barrel` file because it uses the TypeScript compiler API\n\nIn addition, `ctix` will auto-generate `barrel` files so that a single `index.d.ts` file can be generated correctly when using the [rollup-plugin-dts](https://github.com/Swatinem/rollup-plugin-dts) plugin. Now you can develop your TypeScript library projects more easily!\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [Why ctix?](#why-ctix)\n- [Getting Starts](#getting-starts)\n- [How it works?](#how-it-works)\n  - [Barrel file](#barrel-file)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Saving Configuration](#saving-configuration)\n  - [include \\\u0026 exclude file](#include--exclude-file)\n    - [How can I include wanted files?](#how-can-i-include-wanted-files)\n    - [How can I exclude unwanted files?](#how-can-i-exclude-unwanted-files)\n  - [eslint style inline comment](#eslint-style-inline-comment)\n    - [@ctix-exclude](#ctix-exclude)\n    - [@ctix-exclude-next](#ctix-exclude-next)\n    - [@ctix-generation-style](#ctix-generation-style)\n    - [@ctix-declaration](#ctix-declaration)\n  - [Programming interface](#programming-interface)\n- [Requirement](#requirement)\n- [Important](#important)\n- [Generation Style](#generation-style)\n- [More information](#more-information)\n- [Examples](#examples)\n- [What is difference Re-Map paths?](#what-is-difference-re-map-paths)\n- [Option](#option)\n- [License](#license)\n- [References](#references)\n\n## Getting Starts\n\n```bash\nnpm install ctix --save-dev\nnpx ctix init\nnpx ctix build\n```\n\n`ctix` provides interactive prompts to help you create the configuration file. Execute the `ctix init` command to create a configuration file.\n\n## How it works?\n\nThe graph below outlines the behavioral flow of `ctix`.\n\n```mermaid\nflowchart LR\n    START(start) --\u003e |execute cli|ctix\n    ctix --\u003e |TypeScript Compiler API| INP01[Source Code files]\n    ctix --\u003e |TypeScript Compiler API| INP02[\"tsconfig.json\"]\n    ctix --\u003e |json, json5, yaml| INP03[\".ctirc\"]\n    INP01 --\u003e TF[/Summray target source files/]\n    INP02 --\u003e TF\n    INP03 --\u003e TF\n    TF --\u003e TS[/Summray target export statements/]\n    TS --\u003e IW[\"index.ts file generation\"]\n    IW --\u003e END(end)\n```\n\nBecause `ctix` uses the TypeScript Compiler API to summary target files and extract export statements, developers don't need to write source code in a special format or make any changes to existing code to make it work.\n\n### Barrel file\n\nA [barrel](https://basarat.gitbook.io/typescript/main-1/barrel) is a way to rollup exports from several modules into a single convenient module. The barrel itself is a module file that re-exports selected exports of other modules.\n\n- [TypeScript Deep Dive - barrel](https://basarat.gitbook.io/typescript/main-1/barrel)\n- [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n- [In-Depth guide for TypeScript Library](https://dev.to/imjuni/in-depth-guide-for-typescript-library-project-o1j)\n\n## Installation\n\n```bash\nnpm install ctix --save-dev\n```\n\n## Usage\n\n```bash\n# bundle mode\nctix build --mode bundle -p ./tsconfig.json -o ./src\n\n# create mode\nctix build --mode create -p ./tsconfig.json --start-from ./src\n\n# module mode\nctix build --mode module -p ./tsconfig.json -o ./src/components\n```\n\nThe mode in which the `barrel` file is to be generated. There is a create mode that generates an `barrel` file per directory, a bundle mode that generates a single `barrel` file, and a module mode that generates an `barrel` file by filename for `vue`, `sevelte`, etc.\n\n| `bundle` mode                              | `create` mode                              | `module` mode                              |\n| ------------------------------------------ | ------------------------------------------ | ------------------------------------------ |\n| ![bundle mode](static/img/bundle-mode.png) | ![create mode](static/img/create-mode.png) | ![module mode](static/img/module-mode.png) |\n\nCheck out the `.ctirc` in [examples/type10](https://github.com/imjuni/ctix/blob/master/examples/type10/.ctirc) to see how to utilize the `module` mode.\n\n### Saving Configuration\n\nYou can save frequently used configurations. ctix supports saving settings in `package.json`, `tsconfig.json`, or a `.ctirc` file. You can easily create a basic configuration using the `ctix init` command.\n\n```bash\n# generate base configuration\nctix init\n```\n\n### include \u0026 exclude file\n\n`ctix` needs a list of files to generate the `index.ts` file. You can provide this list using the `--include` option, which supports glob patterns. If you don't use the `--include` option, ctix will use the `include` setting from the `.ctirc` file. If neither the `--include` option nor the `.ctirc` file is provided, ctix will fall back to the `include` field in the `tsconfig.json` file.\n\n![include-exclude-diagram](/static/img/file-include-exclude.png)\n\nThis diagram shows the file include/exclude mechanism.\n\n#### How can I include wanted files?\n\n`ctix` gets a glob pattern to generate the `index.ts` file. The glob pattern is obtained from various configuration files such as:\n\n1. Glob pattern from cli argument `--include`\n2. Glob patterns from the `include` field in the `.ctirc` configuration file\n3. Glob patterns from the `include` field in the `tsconfig.json` configuration file\n\nIf your `index.ts` file is empty or a warning is displayed, please check the above configuration.\n\n#### How can I exclude unwanted files?\n\nThere are two ways to do this. The first is to create a `.ctirc` file and set the include or exclude value, which works similarly to the include and exclude values in the `tsconfig.json` file. The second is to comment out `@ctix-exclude` at the top of the files you want to exclude, such as eslint.\n\n\u003e `.ctirc`\n\n```json\n{\n  \"options\": {\n    \"mode\": \"bundle\",\n    \"exclude\": [\"**/*.storybook.tsx\"]\n  }\n}\n```\n\nIf you want to use a `.ctirc` file, I recommend creating one with the `npx ctix init` command.\n\n### eslint style inline comment\n\nYou can add configurations using eslint-style inline comments.\n\n#### @ctix-exclude\n\nIf you want to include an entire directory but exclude certain files, instead of writing a complex glob pattern, you can simply use inline comments to exclude the specific files.\n\n```tsx\n/** @ctix-exclude */\n\nconst Button = () =\u003e {\n  return \u003cbutton\u003eSample\u003c/button\u003e;\n};\n```\n\n#### @ctix-exclude-next\n\nWhen exporting multiple classes and functions, you can exclude one or two of them if needed.\n\n```tsx\nconst Button = () =\u003e {};\n\nconst GroupButton = () =\u003e {};\n\n// @ctix-exclude-next\nconst UnwantedButton = () =\u003e {};\n\nconst Checkbox = () =\u003e {};\n```\n\n#### @ctix-generation-style\n\n```ts\n/** @ctix-generation-style default-alias-named-destructive */\nconst Button = () =\u003e {};\n\nconst GroupButton = () =\u003e {};\n\n// @ctix-exclude-next\nconst UnwantedButton = () =\u003e {};\n\nconst Checkbox = () =\u003e {};\n```\n\nThe export syntax in the `index.ts` file is determined by the chosen generation style. For more details, refer to the [More about Generation Style](doc/IN_DEPTH_GEN_STYLE.md) documentation.\n\n#### @ctix-declaration\n\nWhen `ctix` generates the `index.ts` file, it uses [prettier](https://prettier.io/) and [prettier-plugin-organize-imports](https://www.npmjs.com/package/prettier-plugin-organize-imports) to check if the files to be exported are used. During this process, files that only contain `declare module` are excluded. This can cause issues if you intend to bundle type files. However, if you add `@ctix-declaration` to the file, it will be included in the `index.ts` file. Keep in mind that `@ctix-declaration` is applied after the exclude option, so make sure the file is not included in the exclude option.\n\n\u003e @ctix-declaration does not work when used with export statements in the same file.\n\n```ts\n/** @ctix-declaration */\n\ndeclare module '*.vue' {\n  import Vue from 'vue';\n  export default Vue;\n}\n```\n\n### Programming interface\n\nWhen using task runners like Gulp and Just, as well as bundlers like webpack and rollup, you need a programming interface to add ctix.\n\n| function     | option                                                                                                                                           | descryption                  |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |\n| building     | [TCommandBuildOptions](src/configs/interfaces/TCommandBuildOptions.ts)                                                                           | Execute the `build` command  |\n| initializing | [TCommandInitOptions](src/configs/interfaces/TCommandInitOptions.ts)                                                                             | Execute the `init` command   |\n| removing     | [TCommandRemoveOptions](src/configs/interfaces/TCommandRemoveOptions.ts), [TCommandBuildOptions](src/configs/interfaces/TCommandBuildOptions.ts) | Execute the `remove` command |\n\nCheck out the [example code](doc/PROGRAMMING_INTERFACE.md).\n\n## Requirement\n\n- Node.js 18\n- TypeScript\n\n## Important\n\n`ctix` does not work in JavaScript code because it uses TypeScript API, please use it **`before`** Babel translation or TypeScript compilation.\n\n## Generation Style\n\nThe handling of the `default export` is an important issue, but many bundlers and type bundlers handle the `default export` differently, so ctix provides many ways to create a `default export`.\n\nYou can change the `generation style` of the entire project by setting the `generation-style` option, or you can change the `generation style` of only certain files by adding the `@ctix-generation-style` inline comment at the top of the file.\n\n- [More about Generation Style](doc/IN_DEPTH_GEN_STYLE.md)\n\n## More information\n\n- [Applying a font file to your source code](doc/IN_DEPTH_FONT.md)\n- [Applying a Vue.js components to your source code](doc/IN_DEPTH_VUE.md)\n- [Applying a include, exclude configuration to `.ctirc`](doc/IN_DEPTH_EXCLUDE.md)\n\n## Examples\n\nIn the examples directory, you can find cases where `ctix` has been applied to various projects. For detailed explanations, please refer to the [Examples README.md](examples/README.md) file.\n\n| Directory Name | Purpose                                                                        |\n| -------------- | ------------------------------------------------------------------------------ |\n| type03         | When there are duplicate names in the entire project                           |\n| type05         | For React projects                                                             |\n| type06         | When using TypeScript enums                                                    |\n| type07         | When using destructive operations on variables for named exports               |\n| type09         | When using TTF fonts by declaring them as modules and using them in TypeScript |\n| type10         | For Vue.js projects                                                            |\n| type11         | When using Component Props in React projects                                   |\n\n## What is difference Re-Map paths?\n\nIt is not recommended to use `index.ts` file to re-map paths or shorten the paths. If you want to shorten the paths use [Re-Map paths](https://www.typescriptlang.org/tsconfig#paths) feature in TypeScript compilerOptions. `ctix` is recommended for webpack and rollup.js, typedoc entrypoint and TypeScript declaration file bundling.\n\n## Option\n\n- build command\n  - [bundle mode](doc/OPTION_BUILD_BUNDLE.md)\n  - [create mode](doc/OPTION_BUILD_CREATE.md)\n  - [module mode](doc/OPTION_BUILD_MODULE.md)\n- [remove command](doc/OPTION_REVMOE.md)\n\n## License\n\nThis software is licensed under the [MIT](LICENSE).\n\n## References\n\n- [AST browser](https://ts-ast-viewer.com/)\n- [Tree generator](https://tree.nathanfriend.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimjuni%2Fctix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimjuni%2Fctix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimjuni%2Fctix/lists"}