https://github.com/kodiyak/modpack
⚡ A flexible, browser-first module system powered by es-module-shims.
https://github.com/kodiyak/modpack
es-module-shims esm javascript module-resolver open-source runtime sandbox typescript zero-config
Last synced: 20 days ago
JSON representation
⚡ A flexible, browser-first module system powered by es-module-shims.
- Host: GitHub
- URL: https://github.com/kodiyak/modpack
- Owner: kodiyak
- Created: 2025-06-29T05:11:51.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-07-26T05:16:57.000Z (9 months ago)
- Last Synced: 2025-11-30T03:44:45.787Z (5 months ago)
- Topics: es-module-shims, esm, javascript, module-resolver, open-source, runtime, sandbox, typescript, zero-config
- Language: TypeScript
- Homepage:
- Size: 2.22 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Modpack - Modular and Flexible TypeScript/JavaScript Runtime
## Introduction
**Modpack** is a modular JavaScript runtime that allows you to run JavaScript and TypeScript code in a flexible and isolated environment, built on top of `es-module-shims`. It supports various plugins for module resolution, caching, and code transformation, redefining how modules are processed at runtime.
### Why Modpack?
In today's web development, rigid build tools often limit innovation. Modpack offers a powerful alternative for scenarios demanding **unprecedented control** over module handling. It helps you:
- **Gain Granular Control:** Fine-tune every step of module processing, moving beyond monolithic bundlers.
- **Embrace Extreme Modularity:** Build custom pipelines by adding, removing, or reordering plugins.
- **Power Dynamic Environments:** Perfect for code playgrounds, online editors, and any app needing real-time code manipulation.
- **Leverage Modern Tech:** We stand on the shoulders of giants, orchestrating `es-module-shims` for robust module loading and `SWC-Wasm` for blazing-fast code transformations directly in the browser.
### Installation
Let's walk through a simple example to get Modpack up and running. This demo will show you how to set up Modpack with essential plugins to load, transform, and execute a simple React component from our virtual file system.
```package-install
@modpack/core @modpack/plugins
```
### Import Modpack
```ts
import { Modpack } from "@modpack/core";
import {
cache,
external,
logger,
resolver,
swc,
virtual,
} from "@modpack/plugins";
```
### Create a Modpack Instance
```ts
const modpack = await Modpack.boot({
debug: false, // Set to true for debugging
plugins: [
// **resolver**: Handles how module paths are found, supporting aliases (`@/`) and file extensions.
resolver({
extensions: [".js", ".ts", ".tsx", ".jsx"],
alias: { "@/": "/src/" },
index: true,
}),
// **cache**: Optimizes fetching by storing and serving previously loaded modules.
cache(),
// **virtual**: Enables Modpack to read modules directly from its in-memory file system (`modpack.fs`).
virtual(),
// **external**: Resolves and fetches modules from external URLs, like CDNs (e.g., from `https://esm.sh/*`).
external(),
// **swc**: Transforms your TypeScript and JSX code into standard JavaScript, essential for React.
swc({
extensions: [".js", ".ts", ".tsx", ".jsx"],
jsc: {
target: "es2022",
parser: {
syntax: "typescript",
tsx: true,
},
},
sourceMaps: true,
module: {
type: "es6",
strict: false,
ignoreDynamic: true,
importInterop: "swc",
},
}),
// **logger**: Provides detailed logs of Modpack's operations, very useful for debugging your pipeline.
logger(),
],
});
```
### Minimal React Application
```ts
modpack.fs.writeFile(
"/main.jsx",
`import { createRoot } from 'react-dom/client'
import { useState } from 'react';
const Application = () => {
const [count, setCount] = useState(0);
return (
Count: {count}
setCount(count + 1)}>Increment
setCount(count - 1)}>Decrement
)
}
createRoot(document.getElementById('modpackRoot')).render(
,
)`
);
```
### Run the Module
Finally, tell Modpack which module to load and execute.
```ts
await modpack.mount("/main.jsx");
```
After calling `modpack.mount()`, Modpack will process `/main.jsx` through its configured pipeline:
1. The virtual plugin's resolver identifies `/main.jsx` in the virtual file system.
2. The virtual plugin's fetcher retrieves the content of `/main.jsx` from `modpack.fs`.
3. The `swc` transformer transpiles the JSX/TypeScript code into standard JavaScript.
4. The JavaScript code is then executed in your environment, rendering the React Application component into the `
` element you prepared.
5. You should now see the React counter application running in your browser!