ctix

ctix - Next generation Create TypeScript barrel

entrypoint barrel file automatically generated cli tool

Why ctix?

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,

1. automatically extracts statement with the export keyword applied
2. generate a single barrel file or directory-specific barrel files
3. automatically generate configuration files via interactive prompts
4. automatically add type keyword to interface, type aliases to indicate they are pure types
   • eg. export { type IAmSuperHero } from './marvel';
5. can be set to exception files via comments in source code files (eslint style)
6. 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!

Table of Contents

• Why ctix?
• Getting Starts
• How it works?
  • Barrel file
• Installation
• Usage
  • How can I exclude unwanted files?
  • Programming interface
• Requirement
• Important
• Generation Style
• More information
• What is difference Re-Map paths?
• Option
• License
• References

Getting Starts

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.

How it works?

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.

Barrel file

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

Installation

npm install ctix --save-dev

Usage

# 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 example/type10 to see how to utilize the module mode.

How can I exclude unwanted files?

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.

eslint style inline comment

// @ctix-exclude

const Button = () => {
  return <button>Sample</button>
}

Programming interface

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.

Requirement

• Node.js 18
• TypeScript

Important

ctix does not work in JavaScript code because it uses TypeScript API, please use it before Babel translation or TypeScript compilation.

Generation Style

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.

• More about Generation Style

More information

• Applying a font file to your source code
• Applying a Vue.js components to your source code
• Applying a include, exclude configuration to .ctirc

What is difference Re-Map paths?

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.

Option

• build command
  • bundle mode
  • create mode
  • module mode
• remove command

License

This software is licensed under the MIT.

References

• AST browser
• Tree generator