entrypoint barrel
file automatically generated cli tool
Have 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 to automatically generate the barrel
file by searching your TypeScript project for functions and variables with the export keyword added.
To summarize,
- automatically extracts statement with the export keyword applied
- generate a single
barrel
file or directory-specificbarrel
files - automatically generate configuration files via interactive prompts
- automatically add type keyword to interface, type aliases to indicate they are pure types
- eg.
export { type IAmSuperHero } from './marvel';
- eg.
- can be set to exception files via comments in source code files (eslint style)
- always generates a compilable
barrel
file because it uses the TypeScript compiler API
In 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 plugin. Now you can develop your TypeScript library projects more easily!
- Why ctix?
- Getting Starts
- How it works?
- Installation
- Usage
- Requirement
- Important
- Generation Style
- More information
- Examples
- What is difference Re-Map paths?
- Option
- License
- References
npm install ctix --save-dev
npx ctix init
npx ctix build
ctix
provides interactive prompts to help you create the configuration file. Execute the ctix init
command to create a configuration file.
The graph below outlines the behavioral flow of ctix
.
flowchart LR
START(start) --> |execute cli|ctix
ctix --> |TypeScript Compiler API| INP01[Source Code files]
ctix --> |TypeScript Compiler API| INP02["tsconfig.json"]
ctix --> |json, json5, yaml| INP03[".ctirc"]
INP01 --> TF[/Summray target source files/]
INP02 --> TF
INP03 --> TF
TF --> TS[/Summray target export statements/]
TS --> IW["index.ts file generation"]
IW --> END(end)
Because 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.
A 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.
- TypeScript Deep Dive - barrel
- How we optimized package imports in Next.js
- In-Depth guide for TypeScript Library
npm install ctix --save-dev
# bundle mode
ctix build --mode bundle -p ./tsconfig.json -o ./src
# create mode
ctix build --mode create -p ./tsconfig.json --start-from ./src
# module mode
ctix build --mode module -p ./tsconfig.json -o ./src/components
The 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.
bundle mode |
create mode |
module mode |
---|---|---|
![]() |
![]() |
![]() |
Check out the .ctirc
in examples/type10 to see how to utilize the module
mode.
You 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.
# generate base configuration
ctix init
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.
ctix
gets a glob pattern to generate the index.ts
file. The glob pattern is obtained from various configuration files such as:
- Glob pattern from cli argument
--include
- Glob patterns from the
include
field in the.ctirc
configuration file - Glob patterns from the
include
field in thetsconfig.json
configuration file
If your index.ts
file is empty or a warning is displayed, please check the above configuration.
There 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.
.ctirc
{
"options": {
"mode": "bundle",
"exclude": ["**/*.storybook.tsx"]
}
}
If you want to use a .ctirc
file, I recommend creating one with the npx ctix init
command.
You can add configurations using eslint-style inline comments.
If 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.
/** @ctix-exclude */
const Button = () => {
return <button>Sample</button>;
};
When exporting multiple classes and functions, you can exclude one or two of them if needed.
const Button = () => {};
const GroupButton = () => {};
// @ctix-exclude-next
const UnwantedButton = () => {};
const Checkbox = () => {};
/** @ctix-generation-style default-alias-named-destructive */
const Button = () => {};
const GroupButton = () => {};
// @ctix-exclude-next
const UnwantedButton = () => {};
const Checkbox = () => {};
The export syntax in the index.ts
file is determined by the chosen generation style. For more details, refer to the More about Generation Style documentation.
When ctix
generates the index.ts
file, it uses prettier and 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.
/** @ctix-declaration */
declare module '*.vue' {
import Vue from 'vue';
export default Vue;
}
When using task runners like Gulp and Just, as well as bundlers like webpack and rollup, you need a programming interface to add ctix.
function | option | descryption |
---|---|---|
building | TCommandBuildOptions | Execute the build command |
initializing | TCommandInitOptions | Execute the init command |
removing | TCommandRemoveOptions, TCommandBuildOptions | Execute the remove command |
Check out the example code.
- Node.js 18
- TypeScript
ctix
does not work in JavaScript code because it uses TypeScript API, please use it before
Babel translation or TypeScript compilation.
The 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
.
You 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.
- Applying a font file to your source code
- Applying a Vue.js components to your source code
- Applying a include, exclude configuration to
.ctirc
In 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 file.
Directory Name | Purpose |
---|---|
type03 | When there are duplicate names in the entire project |
type05 | For React projects |
type06 | When using TypeScript enums |
type07 | When using destructive operations on variables for named exports |
type09 | When using TTF fonts by declaring them as modules and using them in TypeScript |
type10 | For Vue.js projects |
type11 | When using Component Props in React projects |
It 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 feature in TypeScript compilerOptions. ctix
is recommended for webpack and rollup.js, typedoc entrypoint and TypeScript declaration file bundling.
- build command
- remove command
This software is licensed under the MIT.