https://github.com/artiomtr/aqu

🌊 Powerful tool for easy typescript/javascript package development powered by esbuild and DTS bundle generator.
https://github.com/artiomtr/aqu
bundle cli npm typescript
Last synced: about 1 year ago
JSON representation
🌊 Powerful tool for easy typescript/javascript package development powered by esbuild and DTS bundle generator.
Host: GitHub
URL: https://github.com/artiomtr/aqu
Owner: ArtiomTr
License: mit
Created: 2021-02-13T13:53:25.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2023-07-20T05:29:49.000Z (almost 3 years ago)
Last Synced: 2025-04-29T15:04:39.691Z (about 1 year ago)
Topics: bundle, cli, npm, typescript
Language: TypeScript
Homepage:
Size: 39.8 MB
Stars: 3
Watchers: 1
Forks: 4
Open Issues: 11
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          


  





  🌊 Aqu





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





  

    

  

  

    

  

  

    

  

  

    

  





  Install → 

  Create package → 

  Customize → 

  Develop → 

  Publish



---

## Inspiration

This package highly inspired by [TSDX](https://github.com/formium/tsdx), [Microbundle](https://github.com/developit/microbundle), [Create React Library](https://github.com/transitive-bullshit/create-react-library#readme).

## ✨ Features 

- One dependency for your code bundling 📦

- Supports vanilla JS, [TypeScript](https://github.com/microsoft/TypeScript#readme) and [React](https://github.com/facebook/react/#readme) ⚛

- No dealing with configurations (automatically generates CJS and esm outputs) ⚙

- Easy project creation, build, management 🔧

- Supports different package managers - [npm](https://github.com/npm/cli#readme), [yarn](https://github.com/yarnpkg/berry#readme) and [pnpm](https://github.com/pnpm/pnpm#readme) 🚀

- Fast, optimized builds thanks to [esbuild](https://github.com/evanw/esbuild#readme) ⏩

- Generates types, using common emit or [dts bundle](https://github.com/timocov/dts-bundle-generator#readme)

- Supports tree shaking 🗑

- Automatically configures [ESLint](https://github.com/eslint/eslint#readme), [Prettier](https://github.com/prettier/prettier#readme), [Jest](https://github.com/facebook/jest#readme) 📃

- 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: 

```sh

npm i -g aqu

```

Then, you can create new package:

```sh

aqu create 

```

### 🗾 Local installation:

```sh

npm i aqu -D

```

Then, add to your `package.json`:

```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`:

```json

{

    ...

    "source": "my/entry.js"

}

```

Or, if you want to specify multiple entrypoints, you can do it in [aqu configuration file](#configuration).

## ⚒ New package 

For creating new package, we recommend to install [aqu globally](#global-installation).

In the shell, enter the command:

```sh

aqu create

```

Or using npx:

```sh

npx aqu create

```

Enter the details about your package and pick a template. Examples of generated projects you can find [here](https://github.com/ArtiomTr/aqu/tree/master/example)

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

```sh

npx aqu create  -y

```

## ⚙ Configuration 

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

Default **aqu** configuration:

```js

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 https://github.com/timocov/dts-bundle-generator

	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:

```sh

aqu build --config=myconfig.js

```

### 📃 Config schema

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

```js

// 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](#name)

2. [input](#input)

3. [outdir](#outdir)

4. [outfile](#outfile)

5. [format](#format)

6. [cjsMode](#cjsMode)

7. [declaration](#declaration)

8. [tsconfig](#tsconfig)

9. [incremental](#incremental)

10. [externalNodeModules](#externalNodeModules)

11. [buildOptions](#buildOptions)

12. [watchOptions](#watchOptions)

#### name

type: `string`

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

#### input

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.

#### outdir

type: `string`

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

#### outfile

type: `string`

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

#### format

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](https://github.com/evanw/esbuild#readme).

#### cjsMode

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"`

#### declaration

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](https://github.com/timocov/dts-bundle-generator#readme). Default `bundle`.

#### tsconfig

type: `string`

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

#### incremental

type: `boolean`

Build incrementally. Default `true`. For more information, see [esbuild](https://github.com/evanw/esbuild#readme).

#### externalNodeModules

type: `boolean`

Should exclude node_modules packages from bundle? Default `true`.

#### buildOptions

type: `ESBuildOptions`

Specify custom [esbuild options](https://esbuild.github.io/api/#simple-options).

#### watchOptions

type: `ChokidarOptions`

Specify custom [chokidar watch options](https://github.com/paulmillr/chokidar#readme).

### Other configurations

**aqu** creates default configs for [ESLint](https://github.com/eslint/eslint#readme), [Prettier](https://github.com/prettier/prettier#readme), [Jest](https://github.com/facebook/jest#readme). 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.

### build

Run command to build your package.

Usage:

```sh

aqu build

```

### watch

Watch your files and automatically rebuild project

Usage:

```sh

aqu watch

```

### lint

Lint files using ESLint.

Usage:

```sh

aqu lint

```

### test

Run jest. Passes all rest arguments to jest.

Usage:

```sh

aqu test.

```

## ✨ Publishing your package 

We highly recommend to use [np](https://github.com/sindresorhus/np#readme) for your package publishing.

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

```sh

npm run publish

```

Or

```sh

yarn publish

```

## Related

- [ESBuild](https://github.com/evanw/esbuild#readme) - An extremely fast JavaScript bundler

- [DTS Bundle generator](https://github.com/timocov/dts-bundle-generator) - Tool to generate a single bundle of dts

- [Microbundle](https://github.com/developit/microbundle) - Zero-configuration bundler for tiny JS libs, powered by Rollup.

- [TSDX](https://github.com/formium/tsdx) - Zero-config TypeScript package development

- [Create React Library](https://github.com/transitive-bullshit/create-react-library#readme) - CLI for easily bootstrapping modern react libraries

## License

MIT © [Artiom Tretjakovas](https://github.com/ArtiomTr)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/artiomtr/aqu

Awesome Lists containing this project

README

🌊 Aqu
