git.zone/tsbundle
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(readme): update README to add interactive setup (tsbundle init), expand quick start and usage examples, include pnpm install, document embedding/base64ts output with Deno example, add project structure recommendations, and clarify license/trademark wording

Browse Source
This commit is contained in:
Jürgen Kunz
2026-01-12 00:06:11 +00:00
parent e3f3dbe1f7
commit 51b7b24607
3 changed files with 206 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
changelog.md
View File

@@ -1,5 +1,15 @@
# Changelog # Changelog
## 2026-01-12 - 2.7.2 - fix(readme)
update README to add interactive setup (tsbundle init), expand quick start and usage examples, include pnpm install, document embedding/base64ts output with Deno example, add project structure recommendations, and clarify license/trademark wording
- Add interactive setup command: `tsbundle init` and updated Quick Start flow
- Include pnpm global install instruction in installation section
- Replace API example with clarified build instructions and new bundle presets (element, website, npm, custom)
- Document embedded bundle output (base64ts) and Deno usage example for decoding/serving files
- Add recommended project structure and formatting improvements (emoji/icons, section reorganizations)
- Clarify license link and expand trademark wording to mention third-party trademarks and approval requirements
## 2026-01-11 - 2.7.1 - fix(package.json) ## 2026-01-11 - 2.7.1 - fix(package.json)
update repository URL to code.foss.global update repository URL to code.foss.global

402
readme.md
View File

@@ -1,6 +1,6 @@
# @git.zone/tsbundle # @git.zone/tsbundle
A powerful multi-bundler tool supporting esbuild, rolldown, and rspack for painless bundling of web projects. A powerful multi-bundler tool supporting **esbuild**, **rolldown**, and **rspack** for painless bundling of web projects. 🚀
## Issue Reporting and Security ## Issue Reporting and Security
@@ -14,136 +14,128 @@ npm install -g @git.zone/tsbundle
# Local installation for project usage # Local installation for project usage
npm install --save-dev @git.zone/tsbundle npm install --save-dev @git.zone/tsbundle
# Or with pnpm
pnpm add -g @git.zone/tsbundle
``` ```
## Quick Start ## Quick Start ⚡
### CLI Usage ### Interactive Setup
The simplest way to bundle your project: The easiest way to get started is with the interactive wizard:
```bash
tsbundle init
```
This will guide you through setting up your bundle configuration with preset options:
- **element** - Web component / element bundle (`./ts_web/index.ts` → `./dist_bundle/bundle.js`)
- **website** - Full website with HTML and assets (`./ts_web/index.ts` → `./dist_serve/bundle.js`)
- **npm** - NPM package bundle (`./ts/index.ts` → `./dist_bundle/bundle.js`)
- **custom** - Configure everything manually
### Build Your Bundles
Once configured, simply run:
```bash ```bash
# Bundle with default settings (from ./ts_web/index.ts to ./dist_bundle/bundle.js)
tsbundle tsbundle
# Bundle with custom paths
tsbundle --from="./src/index.ts" --to="./dist/bundle.js"
# Production build with minification
tsbundle --from="./src/index.ts" --to="./dist/bundle.js" --production
# Use a specific bundler
tsbundle --bundler=rolldown
``` ```
### API Usage That's it! Your bundles will be built according to your `npmextra.json` configuration.
```typescript
import { TsBundle } from '@git.zone/tsbundle';
const bundler = new TsBundle();
// Basic usage
await bundler.build(
process.cwd(), // working directory
'./src/index.ts', // entry point
'./dist/bundle.js', // output file
{ bundler: 'esbuild' }, // options
);
// Production build with rolldown
await bundler.build(process.cwd(), './src/index.ts', './dist/bundle.min.js', {
bundler: 'rolldown',
production: true,
});
```
## Available Bundlers
tsbundle supports three modern bundlers, each with its own strengths:
- **esbuild** (default): Extremely fast, great for development
- **rolldown**: Rust-based bundler with excellent tree-shaking
- **rspack**: High-performance bundler with webpack compatibility
Select your bundler using the `--bundler` flag in CLI or the `bundler` option in API.
## CLI Commands ## CLI Commands
### Default Command | Command | Description |
|---------|-------------|
| `tsbundle` | Build all bundles from `npmextra.json` configuration |
| `tsbundle custom` | Same as above (explicit) |
| `tsbundle init` | Interactive wizard to create/update bundle configuration |
Bundle TypeScript/JavaScript projects: ## Configuration 📝
```bash tsbundle uses `npmextra.json` for configuration. Here's an example:
tsbundle [options]
Options: ```json
--from Source entry point (default: ./ts_web/index.ts) {
--to Output bundle path (default: ./dist_bundle/bundle.js) "@git.zone/tsbundle": {
--production Enable production mode with minification "bundles": [
--bundler Choose bundler: esbuild, rolldown, or rspack {
--commonjs Output CommonJS format instead of ESM "from": "./ts_web/index.ts",
--skiplibcheck Skip TypeScript library checking "to": "./dist_bundle/bundle.js",
"outputMode": "bundle",
"bundler": "esbuild",
"production": false
},
{
"from": "./ts_web/index.ts",
"to": "./dist_serve/bundle.js",
"outputMode": "bundle",
"bundler": "esbuild",
"includeFiles": ["./html/**/*.html", "./assets/**/*"]
}
]
}
}
``` ```
### Specialized Commands ### Bundle Configuration Options
#### `tsbundle element` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `from` | `string` | - | Entry point TypeScript file |
| `to` | `string` | - | Output file path |
| `outputMode` | `"bundle"` \| `"base64ts"` | `"bundle"` | Output format (see below) |
| `bundler` | `"esbuild"` \| `"rolldown"` \| `"rspack"` | `"esbuild"` | Which bundler to use |
| `production` | `boolean` | `false` | Enable minification |
| `includeFiles` | `string[]` | `[]` | Glob patterns for additional files (HTML, assets) |
Bundle web components with standard naming conventions: ### Output Modes
```bash #### `bundle` (default)
tsbundle element Standard JavaScript bundle output. Additional files specified in `includeFiles` are copied to the output directory.
# Bundles from ./ts_web/elements/<elementName>.ts to ./dist_bundle/bundle.js
#### `base64ts`
Generates a TypeScript file with base64-encoded content - perfect for **Deno compile** scenarios where you need everything embedded in a single executable:
```typescript
// Auto-generated by tsbundle
export const files: { path: string; contentBase64: string }[] = [
{ path: "bundle.js", contentBase64: "Y29uc3QgaGVsbG8gPSAid29ybGQi..." },
{ path: "index.html", contentBase64: "PCFET0NUWVBFIGh0bWw+..." },
];
``` ```
#### `tsbundle npm` ## Available Bundlers 🔧
Bundle npm packages for distribution: tsbundle supports three modern bundlers:
```bash | Bundler | Speed | Best For |
tsbundle npm |---------|-------|----------|
# Prepares your package for npm publishing | **esbuild** | ⚡⚡⚡ Blazing fast | Development, quick iterations |
``` | **rolldown** | ⚡⚡ Fast | Production builds, tree-shaking |
| **rspack** | ⚡⚡ Fast | Webpack compatibility |
#### `tsbundle website` ## API Usage
Full website bundling with HTML processing and asset handling:
```bash
tsbundle website
# Bundles JavaScript, processes HTML, and copies assets
```
## API Reference
### TsBundle Class ### TsBundle Class
The main bundler class for programmatic usage.
```typescript ```typescript
import { TsBundle } from '@git.zone/tsbundle'; import { TsBundle } from '@git.zone/tsbundle';
const bundler = new TsBundle(); const bundler = new TsBundle();
// Method signature
await bundler.build( await bundler.build(
cwdArg: string, // Working directory process.cwd(), // Working directory
fromArg?: string, // Entry point (default: './ts_web/index.ts') './src/index.ts', // Entry point
toArg?: string, // Output path (default: './dist_bundle/bundle.js') './dist/bundle.js', // Output path
argvArg?: ICliOptions // Configuration options {
): Promise<void> bundler: 'esbuild',
``` production: true
}
#### ICliOptions Interface );
```typescript
interface ICliOptions {
bundler: 'esbuild' | 'rolldown' | 'rspack'; // Bundler to use
production?: boolean; // Enable production optimizations
commonjs?: boolean; // Output CommonJS format
skiplibcheck?: boolean; // Skip TypeScript lib checking
}
``` ```
### HtmlHandler Class ### HtmlHandler Class
@@ -155,156 +147,152 @@ import { HtmlHandler } from '@git.zone/tsbundle';
const htmlHandler = new HtmlHandler(); const htmlHandler = new HtmlHandler();
// Check if HTML files exist
const exists = await htmlHandler.checkIfExists();
// Process HTML with options
await htmlHandler.processHtml({ await htmlHandler.processHtml({
from: './src/index.html', // Source HTML (default: './html/index.html') from: './html/index.html',
to: './dist/index.html', // Output HTML (default: './dist_serve/index.html') to: './dist/index.html',
minify: true, // Enable minification minify: true
}); });
``` ```
### AssetsHandler Class ### AssetsHandler Class
Handle static assets (images, fonts, etc.): Handle static assets:
```typescript ```typescript
import { AssetsHandler } from '@git.zone/tsbundle'; import { AssetsHandler } from '@git.zone/tsbundle';
const assetsHandler = new AssetsHandler(); const assetsHandler = new AssetsHandler();
// Ensure assets directory exists
await assetsHandler.ensureAssetsDir();
// Copy and process assets
await assetsHandler.processAssets({ await assetsHandler.processAssets({
from: './src/assets', // Source directory (default: './assets') from: './assets',
to: './dist/assets', // Output directory (default: './dist_serve/assets') to: './dist/assets'
}); });
``` ```
## Advanced Examples ## Complete Example 🎯
### Building a Modern Web Application ### 1. Initialize your project
```typescript ```bash
import { TsBundle, HtmlHandler, AssetsHandler } from '@git.zone/tsbundle'; tsbundle init
async function buildWebApp() {
const bundler = new TsBundle();
const htmlHandler = new HtmlHandler();
const assetsHandler = new AssetsHandler();
// Bundle the JavaScript
await bundler.build(process.cwd(), './src/app.ts', './dist/app.js', {
bundler: 'rolldown',
production: true,
});
// Process HTML
await htmlHandler.processHtml({
from: './src/index.html',
to: './dist/index.html',
minify: true,
});
// Copy assets
await assetsHandler.processAssets({
from: './src/assets',
to: './dist/assets',
});
console.log('Build complete!');
}
buildWebApp();
``` ```
### Multi-Entry Point Bundling Select "website" preset for a full web application setup.
```typescript ### 2. Your generated config
import { TsBundle } from '@git.zone/tsbundle';
async function buildMultipleEntries() {
const bundler = new TsBundle();
const entries = [
{ from: './src/main.ts', to: './dist/main.js' },
{ from: './src/admin.ts', to: './dist/admin.js' },
{ from: './src/worker.ts', to: './dist/worker.js' },
];
for (const entry of entries) {
await bundler.build(process.cwd(), entry.from, entry.to, {
bundler: 'esbuild',
});
}
}
```
### Development vs Production Builds
```typescript
import { TsBundle } from '@git.zone/tsbundle';
const bundler = new TsBundle();
const isDev = process.env.NODE_ENV === 'development';
await bundler.build(
process.cwd(),
'./src/index.ts',
isDev ? './dist/dev/bundle.js' : './dist/prod/bundle.min.js',
{
bundler: isDev ? 'esbuild' : 'rolldown', // esbuild for speed in dev
production: !isDev, // minify in production
commonjs: false, // use ES modules
},
);
```
## TypeScript Configuration
tsbundle works best with the following TypeScript configuration:
```json ```json
{ {
"compilerOptions": { "@git.zone/tsbundle": {
"target": "ES2022", "bundles": [
"module": "ESNext", {
"moduleResolution": "node", "from": "./ts_web/index.ts",
"esModuleInterop": true, "to": "./dist_serve/bundle.js",
"allowSyntheticDefaultImports": true, "outputMode": "bundle",
"strict": true "bundler": "esbuild",
"includeFiles": ["./html/**/*.html", "./assets/**/*"]
}
]
} }
} }
``` ```
## Best Practices ### 3. Create your entry point
1. **Entry Points**: Keep your entry points in `ts_web/` for web bundles or `ts/` for library bundles ```typescript
2. **Output Structure**: Use `dist_bundle/` for bundled files and `dist_serve/` for web-ready files // ts_web/index.ts
3. **Bundler Selection**: console.log('Hello from tsbundle! 🚀');
- Use `esbuild` for development (fastest)
- Use `rolldown` or `rspack` for production (better optimization) export const app = {
4. **Assets**: Place static assets in the `assets/` directory version: '1.0.0',
5. **HTML**: Keep HTML templates in the `html/` directory init() {
console.log('App initialized');
}
};
app.init();
```
### 4. Build
```bash
tsbundle
```
Your bundle is ready in `./dist_serve/bundle.js` along with any HTML and assets!
## Embedding for Deno Compile 🦕
For single-executable scenarios with Deno:
```bash
tsbundle init
# Select "custom", set outputMode to "base64ts"
```
Config:
```json
{
"@git.zone/tsbundle": {
"bundles": [
{
"from": "./ts_web/index.ts",
"to": "./ts/embedded-bundle.ts",
"outputMode": "base64ts",
"bundler": "esbuild",
"production": true,
"includeFiles": ["./html/index.html"]
}
]
}
}
```
Then in your Deno app:
```typescript
import { files } from './ts/embedded-bundle.ts';
// Decode and serve your embedded files
const bundle = files.find(f => f.path === 'bundle.js');
const html = files.find(f => f.path === 'html/index.html');
const bundleContent = atob(bundle.contentBase64);
const htmlContent = atob(html.contentBase64);
```
## Project Structure Recommendations 📁
```
your-project/
├── ts_web/ # Web bundle entry points
│ └── index.ts
├── ts/ # Library/node entry points
│ └── index.ts
├── html/ # HTML templates
│ └── index.html
├── assets/ # Static assets (images, fonts, etc.)
├── dist_bundle/ # Output for element/npm bundles
├── dist_serve/ # Output for website bundles
└── npmextra.json # tsbundle configuration
```
## License and Legal Information ## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks ### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information ### Company Information
Task Venture Capital GmbH Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works. By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@git.zone/tsbundle', name: '@git.zone/tsbundle',
version: '2.7.1', version: '2.7.2',
description: 'a multi-bundler tool supporting esbuild, rolldown, and rspack for painless bundling of web projects' description: 'a multi-bundler tool supporting esbuild, rolldown, and rspack for painless bundling of web projects'
} }