create-lib-workspace

A lightweight CLI tool to instantly scaffold a local development monorepo workspace for custom JavaScript libraries built with Vite (currently defaults to Javascript setup).

It automatically sets up a multi-entry library with proper ESM/CJS exports, pre-configured example code, and links it to a static test application using your favorite package manager—completely dependency-free.

Installation

You can install this tool globally to make it available anywhere on your system, or run it directly without installation.

1. Global Installation (Recommended)

Install the CLI globally using your preferred package manager:

# Using pnpm
pnpm add -g create-lib-workspace

# Using npm
npm install -g create-lib-workspace

# Using yarn
yarn global add create-lib-workspace

2. Run Without Installation

If you prefer not to install the package globally, you can run it on the fly using executors:

# Using pnpm dlx
pnpm dlx create-lib-workspace

# Using npx
npx create-lib-workspace

# Using yarn dlx
yarn dlx create-lib-workspace

Usage

You can run the command completely empty to start the interactive wizard, or pre-define arguments inline.

# Option A: Interactive Wizard (Recommended)
create-lib-workspace

# Option B: Inline Arguments
create-lib-workspace <workspace-name> <lib-name> <package-name> [pnpm|npm|yarn]

Arguments (Optional if using Wizard)

• <workspace-name>: The name of the root directory for your project.
• <lib-name>: The directory name of the library inside the workspace.
• <package-name>: The actual package name for your package.json fields (e.g., @my-scope/my-lib).
• [package-manager]: Force a specific tool (pnpm, npm, or yarn). Defaults to an interactive selection if omitted.

Example (Inline)

create-lib-workspace my-project core-lib @my-org/core pnpm

⚠️ Important Note During Setup

During execution, the script delegates project scaffolding to Vite's official creator tool.

❌ DO NOT let Vite install dependencies or run immediately if it prompts you to do so. The script will automatically handle the clean-up, structure generation, and global symlinking right after.

What is generated?

The tool scaffolds a clean workspace structured as follows:

my-project/
├── app/                  # Pure static consumer app
│   ├── index.html        # Test page
│   └── main.js           # Example code importing and testing your library locally
└── core-lib/             # Your actual Library (Vite-powered)
    ├── src/
    │   ├── index.js      # Main entry point (with boilerplate example code)
    │   ├── index.test.js # Ready-to-run unit test runner example
    │   └── modifiers/    # Secondary entry point sub-module example
    ├── package.json      # Pre-configured with ESM/CJS exports and testing scripts
    └── vite.config.js    # Pre-configured multi-entry build setup

Workflow / Local Development

Once the setup completes successfully, the library is automatically symlinked to the test app. You can start developing in real-time using two terminal windows:

Terminal 1: Library Watcher

Recompiles your library automatically on every file change. Replace <pkg> with your chosen package manager (pnpm, npm, or yarn).

cd my-project/core-lib
<pkg> run watch

Terminal 2: Test App Server

Serves the consumer application so you can see your library in action.

cd my-project/app

# If you used pnpm:
pnpm dlx vite --open

# If you used npm:
npx vite --open

# If you used yarn:
yarn dlx vite --open

Terminal 3: Test Runner

Run your unit tests inside the library directory using Vitest. Replace <pkg> with your chosen package manager.

cd my-project/core-lib
<pkg> test

License

MIT