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,

automatically extracts statement with the export keyword applied
generate a single barrel file or directory-specific barrel 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';
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!

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.

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 | | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | | bundle mode | create mode | module mode |

Check out the .ctirc in examples/type10 to see how to utilize the module mode.

Saving Configuration

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

include & exclude file

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.

include-exclude-diagram

This diagram shows the file include/exclude mechanism.

How can I include wanted files?

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 the tsconfig.json configuration file

If your index.ts file is empty or a warning is displayed, please check the above configuration.

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

You can add configurations using eslint-style inline comments.

@ctix-exclude

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>;
};

@ctix-exclude-next

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

/** @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.

@ctix-declaration

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

Install / Use

README