Pochade-JS Project

A vanilla JS, CSS and HTML project with Web Workers and Custom HTML Elements as first class citizens.

Using command-panel in your project

Option 1: Script embed (no build step)

<link rel="stylesheet" href="main.css">
<script src="main.min.js" type="module"></script>

<command-panel id="panel"></command-panel>
<script type="module">
  const panel = document.getElementById('panel');
  panel.addCommand('Do Thing', '🎯', () => { /* ... */ });
  panel.on('COMMAND-EXECUTED', (data) => console.log(data));
</script>

• The script must be type="module" — the bundle is an ES module.
• addCommand() is safe to call immediately; no timeout or load-event wait needed.
• Open the panel with Ctrl+Shift+P (or Cmd+Shift+P on macOS), or set a custom shortcut with open-keys="alt+k".
• The component ships with neutral fallback colors. To theme it, define these CSS variables on :root: --background-color, --foreground-color, --secondary-color, --trinary-color, --highlight-color.

Option 2: npm import (bundler or Node)

import CommandPanel from 'command-panel'; // registers <command-panel> and exports the class

Option 3: import the source (bundler required)

import CommandPanel from 'command-panel/src/command-panel.js';

This path imports CSS, so it requires a bundler with a CSS loader (rspack/webpack/Vite). It will not work in plain Node or a browser import map.

Getting Started

Install dependencies:

npm install

Running the Project

To run the project in development mode:

npm start

This will start a development server. By default, it runs on port 3000. You can view the project in your browser.

Building the Project

To build the project for production:

npm build

This will create a dist folder with the bundled and optimized files.

Customizing the Build

You can customize the build output by creating a .env file in the root of the project.

Output Filename

To change the name of the output file, set the OUTPUT_FILE_NAME variable in your .env file.

.env

OUTPUT_FILE_NAME=my-custom-filename.js

If this variable is not set, the output file will default to dist/main.min.js.

Development Server Port

You can also change the development server port by setting the PORT variable in your .env file.

.env

PORT=8080

If this variable is not set, the port will default to 3000.

Project Structure

• src/ - Your JavaScript source files
• styles/ - CSS files
• scripts/ - Build scripts (including Web Worker transformation)
• index.html - Main HTML file
• index.js - Main JavaScript entry point
• index.css - Main CSS file
• rspack.config.js - Rspack configuration

Rspack Build Configuration

Features

The project uses Rspack with the following features configured:

Module Processing

• CSS Processing Pipeline

  • style-loader - Injects CSS into the DOM
  • css-loader - Resolves CSS imports and URLs
  • postcss-loader with cssnano - Minifies and optimizes CSS
  • Source maps enabled in development mode
  • Automatic comment removal in production builds

• JavaScript Processing

  • builtin:swc-loader - Fast JavaScript transpilation
  • Custom transform-workers.js loader - Transforms web worker imports
  • Dynamic imports forced to eager mode for web worker compatibility
  • Source maps enabled in development mode

Web Workers

The build system includes special handling for web workers:

• Custom loader (scripts/transform-workers.js) transforms worker imports
• Dynamic imports are eagerly evaluated for worker compatibility
• Workers are properly bundled and can be imported in your code

Assets Directory

The assets/ folder receives special treatment:

• Development Server: Assets are served from the root path (/) if the directory exists and contains files
• Production Build: Assets are copied to the dist root (not in a subdirectory) via CopyRspackPlugin
• Conditional Loading: Assets are only processed if the directory exists and has files

Place any static files (images, fonts, etc.) in the assets/ directory and they will be accessible from the root path in both dev and production.

Optimization

• splitChunks: false - Bundles everything into a single file
• runtimeChunk: false - No separate runtime chunk
• clean: true - Automatically cleans the dist directory before each build

Development Server

• Serves static files from project root
• Conditionally serves assets directory
• Gzip compression enabled
• Cache-Control headers set to no-store for development
• Configurable port via environment variable

Environment Configuration

• .env file support via dotenv
• OUTPUT_FILE_NAME - Customize output filename (default: main.min.js)
• PORT - Configure dev server port (default: 3000)
• NODE_ENV - Set to production for production builds

Technologies

• Rspack - Fast bundler for development and production
• dataroom-js - Custom HTML elements framework
• Web Workers - For parallel processing
• PostCSS - CSS processing with cssnano optimization
• SWC - Fast JavaScript/TypeScript compiler

Publishing to npm

This project is configured for publishing to npm. Follow these steps to publish:

Before First Publish

1. Update package metadata in package.json:

   • Set the package name (must be unique on npm)
   • Update author with your name and email
   • Update repository, bugs, and homepage URLs with your actual repository
   • Set the initial version (recommend starting with 0.1.0)

2. Verify the package contents:

   npm pack --dry-run

   This shows what files will be included in the package.

3. Test the build:

   npm run build

   Ensure the dist/ directory is created successfully.

Publishing

1. Login to npm (first time only):

   npm login

2. Publish the package:

   npm publish

   The prepublishOnly script will automatically run the build before publishing.

Updating the Package

1. Update the version using npm's version command:

   npm version patch  # For bug fixes (1.0.0 -> 1.0.1)
   npm version minor  # For new features (1.0.0 -> 1.1.0)
   npm version major  # For breaking changes (1.0.0 -> 2.0.0)

2. Publish the update:

   npm publish

What Gets Published

The package includes:

• dist/ - Built production files
• src/ - Source JavaScript files
• styles/ - CSS files
• index.js, index.css, index.html - Entry files
• package.json and related metadata

Development files (rspack config, build scripts, tests, etc.) are excluded via .npmignore.