๐ŸŒŠ Powerful tool for easy typescript/javascript package development

Usage no npm install needed!

<script type="module">
  import aqu from '';


Aqu usage

๐ŸŒŠ Aqu

Powerful tool for easy typescript/javascript package development powered by esbuild and DTS bundle generator.

package version package downloads vulnerabilities issues

Install โ†’ Create package โ†’ Customize โ†’ Develop โ†’ Publish


This package highly inspired by TSDX, Microbundle, Create React Library.

โœจ Features

  • One dependency for your code bundling ๐Ÿ“ฆ
  • Supports vanilla JS, TypeScript and React โš›
  • No dealing with configurations (automatically generates CJS and esm outputs) โš™
  • Easy project creation, build, management ๐Ÿ”ง
  • Supports different package managers - npm, yarn and pnpm ๐Ÿš€
  • Fast, optimized builds thanks to esbuild โฉ
  • Generates types, using common emit or dts bundle
  • Supports tree shaking ๐Ÿ—‘
  • Automatically configures ESLint, Prettier, Jest ๐Ÿ“ƒ
  • Multiple entries and outputs ๐Ÿคนโ€โ™‚๏ธ

๐Ÿ”จ Installation

You can create new package or integrate aqu into existing package. For package creation, we recommend to install aqu globally.

๐ŸŒŽ Global installation:

npm i -g aqu

Then, you can create new package:

aqu create <package>

๐Ÿ—พ Local installation:

npm i aqu -D

Then, add to your package.json:

    "scripts": {
        "build": "aqu build",
        "start": "aqu watch",
        "test": "aqu test",
        "lint": "aqu lint"

By default, aqu will search for index file in src or lib folder (available extensions: .js, .jsx, .cjs, .mjs, .ts, .tsx)

If this doesn't suit for your package, you can specify source property in your package.json:

    "source": "my/entry.js"

Or, if you want to specify multiple entrypoints, you can do it in aqu configuration file.

โš’ New package

For creating new package, we recommend to install aqu globally.

In the shell, enter the command:

aqu create

Or using npx:

npx aqu create

Enter the details about your package and pick a template. Examples of generated projects you can find here

If you don't want to enter all the information, you can automatically pick all defaults, by toggling -y flag:

npx aqu create <package> -y

โš™ Configuration

aqu automatically creates optimal configuration for your package on-the-fly.

Default aqu configuration:

var defaultConfig = {
  format: ['cjs', 'esm'], // will generate multiple outputs: one for cjs and one for esm
  cjsMode: 'mixed', // will generate separate files for development and production
  outdir: 'dist', // default output directory
  declaration: 'bundle', // will bundle declarations using
  externalNodeModules: true, // automatically will mark all node_modules as external
  tsconfig: 'tsconfig.json', // default path to tsconfig
  incremental: true, // will build incrementally
  buildOptions: {}, // custom esbuild options
  watchOptions: {
    // chokidar watch options
    ignored: ['node_modules/**', 'dist/**', 'build/**', 'out/**'], // by default, will ignore those folders
    followSymlinks: false, // will not follow symlinks

For input, aqu will search index file inside lib or src folder (available extensions for index: .js, .jsx, .cjs, .mjs, .ts, .tsx)

Also, aqu will read your package.json and take source option to determine entrypoint, and name for package's name.

You can specify your own aqu configuration. By default, these files will be read inside your working directory:

  1. aqu.config.js
  2. aqu.config.cjs
  3. aqu.config.mjs
  4. aqu.config.ts
  5. aqu.config.json
  6. .aqurc

If your configuration has different name, you can specify --config option for aqu. Example:

aqu build --config=myconfig.js

๐Ÿ“ƒ Config schema

Configuration file can export one configuration, as well as array of configurations. For example:

// aqu.config.js

// this works
module.exports = {
  input: './asdf.js',

// as well as this
module.exports = [
    input: './asdf.js',
    input: './hello.js',

Available configuration options:

  1. name
  2. input
  3. outdir
  4. outfile
  5. format
  6. cjsMode
  7. declaration
  8. tsconfig
  9. incremental
  10. externalNodeModules
  11. buildOptions
  12. watchOptions


type: string

Specify custom library name. By default, aqu will try to load package name from package.json in current working directory.


type: string | string[]

Your library entrypoints. For each entrypoint aqu will generate output files, using this configuration. Default: index file in src or lib directories.


type: string

Directory, where will all files be generaten. Default: dist


type: string

Output file. Do not works when configuration should generate multiple outputs (multiple formats or multiple entrypoints or cjsMode: "multiple")


type: Format | Format[]

Output formats. Available formats: cjs, esm, iife. When cjs format picken, configuration option cjsMode works. Default ["cjs", "esm"] For more information about formats, see esbuild.


type: "development" | "production" | "mixed"

CommonJS generation mode. Works only when format includes cjs. If production - will generate minified bundle, development - normal development build, mixed - will generate both with one entrypoint - index.js. Default "mixed"


type: DeclarationType

Algorithm to emit declarations. Available options - none, normal, bundle. none - do not emit declarations, normal - default declaration emit (same as tsc does), bundle - generate declarations bundle using dts-bundle-generator. Default bundle.


type: string

Path to tsconfig. Default join(process.cwd(), "tsconfig.json").


type: boolean

Build incrementally. Default true. For more information, see esbuild.


type: boolean

Should exclude node_modules packages from bundle? Default true.


type: ESBuildOptions

Specify custom esbuild options.


type: ChokidarOptions

Specify custom chokidar watch options.

Other configurations

aqu creates default configs for ESLint, Prettier, Jest. If you don't like the defaults, you can create your own configuration and override all options.

๐Ÿ”ง Package development

aqu makes your life easier. It automatically handles Jest, ESlint, Prettier, ESBuild and typings emit.


Run command to build your package.


aqu build


Watch your files and automatically rebuild project


aqu watch


Lint files using ESLint.


aqu lint


Run jest. Passes all rest arguments to jest.


aqu test.

โœจ Publishing your package

We highly recommend to use np for your package publishing.

If you have created your package using aqu create, then you can just run:

npm run publish


yarn publish


  • ESBuild - An extremely fast JavaScript bundler
  • DTS Bundle generator - Tool to generate a single bundle of dts
  • Microbundle - Zero-configuration bundler for tiny JS libs, powered by Rollup.
  • TSDX - Zero-config TypeScript package development
  • Create React Library - CLI for easily bootstrapping modern react libraries


MIT ยฉ Artiom Tretjakovas