# fragment-tools

> A web development environment for creative coding

Latest version **0.2.16** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install fragment-tools
pnpm add fragment-tools
yarn add fragment-tools
bun add fragment-tools
```

Provides the command `fragment`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.16 |
| Published | 2026-11-19 |
| First published | 2022-09-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 15 |
| Unpacked size | 878.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 949 |
| Author | Raphaël Améaume |
| Maintainers | raphaelameaume |

## Links

- npm: https://www.npmjs.com/package/fragment-tools
- Repository: https://github.com/raphaelameaume/fragment
- Homepage: https://github.com/raphaelameaume/fragment#readme
- Issues: https://github.com/raphaelameaume/fragment/issues
- npm.io page: https://npm.io/package/fragment-tools

## Dependencies (15)

- [ws](https://npm.io/package/ws.md) ^8.21.0
- [sade](https://npm.io/package/sade.md) ^1.8.1
- [vite](https://npm.io/package/vite.md) ^8.2.0
- [kleur](https://npm.io/package/kleur.md) ^4.1.5
- [gifenc](https://npm.io/package/gifenc.md) 1.0.3
- [svelte](https://npm.io/package/svelte.md) ^5.55.9
- [get-port](https://npm.io/package/get-port.md) ^7.1.0
- [changedpi](https://npm.io/package/changedpi.md) 1.0.4
- [mediabunny](https://npm.io/package/mediabunny.md) ^1.13.3
- [@clack/core](https://npm.io/package/@clack/core.md) ^1.3.1
- [fragment-gl](https://npm.io/package/fragment-gl.md) ^1.0.1
- [milliparsec](https://npm.io/package/milliparsec.md) ^5.1.0
- [convert-length](https://npm.io/package/convert-length.md) 1.0.1
- [is-unicode-supported](https://npm.io/package/is-unicode-supported.md) ^2.0.0
- [@sveltejs/vite-plugin-svelte](https://npm.io/package/@sveltejs/vite-plugin-svelte.md) ^7.1.2

## Recent versions

- 0.2.16 (latest) — 2026-11-19
- 0.2.15 — 2026-06-24
- 0.2.14 — 2026-05-30
- 0.2.13 — 2026-05-29
- 0.2.12 — 2026-01-30
- 0.2.11 — 2025-12-05
- 0.2.10 — 2025-11-17
- 0.2.9 — 2025-09-04
- 0.2.8 — 2025-08-12
- 0.2.7 — 2025-06-30
- 0.2.6 — 2025-05-20
- 0.2.5 — 2025-02-17
- 0.2.4 — 2025-02-14
- 0.2.3 — 2025-02-04
- 0.2.2 — 2025-01-20
- … 14 more at https://npm.io/package/fragment-tools/versions

## README

<h1 align="center">Fragment</h1>
<div align="center">A modern toolkit for creative coding</div>
<br/>

![Screen capture of Fragment, splitted in two columns, the left one has a canvas displaying circles arranged in a grid layout with chromatic aberration, grain and blur effects. The right column contains various controls for colors, circle and grid parameters and an export module with video capabilities](https://github.com/raphaelameaume/fragment/blob/dev/screenshot.jpg?raw=true 'Screen Capture of Fragment')

Fragment lets you sketch, render, and export canvas-based graphics with ease, from quick experiments to production-ready visuals.

## Features

- Start instantly using built-in templates for [Canvas 2D](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API), [p5.js](https://github.com/processing/p5.js/), and [three.js](https://github.com/mrdoob/three.js/)
- Generate live GUI controls directly from your sketch parameters
- Reload GLSL shaders on the fly
- Attach mouse, keyboard, and MIDI inputs directly from the interface or your code
- Organize your creative workspace with flexible window layouts
- Export your sketches as images or videos in standard formats
- Build static bundles ready for production deployment

## Specifications

- Fast development and production builds powered by [Vite](https://vite.dev/)
- Interactive command-line interface on top of [sade](https://github.com/lukeed/sade) and [clack](https://www.clack.cc/)
- Video encoding in the browser with [Mediabunny](https://mediabunny.dev/)
- TypeScript support

## Installation

### With `npx`

```bash
npx fragment-tools sketch.js --new
```

### Installing globally with `--global`

```bash
npm install fragment-tools --global
```

You should now be able to run `fragment` from your command line.

```bash
fragment -v
```

### Installing locally

```bash
npm install fragment-tools
```

## Usage

```bash
# Create a new directory for your sketches
mkdir sketches

# Move into that folder
cd sketches

# Create a sketch from a template
npx fragment sketch.js --new --template=2d

# or with TypeScript
npx fragment sketch.ts --new --template=2d --typescript

## Run an existing sketch
npx fragment sketch.js
```

Learn more about the available flag options in the [CLI docs](./docs/api/CLI.md).

## Example

This is an example of a sketch drawing a blue circle on a black background with a custom control for the radius of the circle.

```js
export let props = {
	background: {
		value: '#0057B8', // create a color input GUI
	},
	fill: {
		value: 'rgba(255, 215, 0, 1)', // create a color input GUI
	},
	size: {
		value: 256, // create a number input GUI
		params: {
			min: 64, // add a range slider
			max: 512,
		},
	},
	shape: {
		value: 'circle', // create a string input
		params: {
			options: ['circle', 'square'], // turns the input into a select with different options
		},
	},
};

export let update = ({ context, width, height, pixelRatio }) => {
	// draw background
	context.fillStyle = props.background.value;

	const w = width * pixelRatio;
	const h = height * pixelRatio;

	context.fillRect(0, 0, w, h);

	// draw circle
	const shape = props.shape.value;
	const size = props.size.value * pixelRatio;

	context.fillStyle = props.fill.value;

	if (shape === 'circle') {
		context.beginPath();
		context.arc(w * 0.5, h * 0.5, size, 0, 2 * Math.PI, false);
		context.fill();
	} else if (shape === 'square') {
		context.fillRect(w * 0.5 - size, h * 0.5 - size, size * 2, size * 2);
	}
};

export let rendering = '2d';
export let fps = 0;
export let name = 'Canvas2D Shape Example';
export let buildConfig = {
	resizing: 'window',
};
```

Learn how to write your own sketch by following the [Getting started](./docs/introduction/getting-started.md) guide, reading the [API docs](./docs/api/sketch.md) or the other [examples](./examples/).

## Contributing

If you find issues, please [file one](https://github.com/raphaelameaume/fragment/issues) with details on how to reproduce it.

Feel free to reach out on [Bluesky](https://bsky.app/profile/raphaelameaume.com) if you want to discuss the project.

## Running it locally

```bash
# Clone or fork the project
git clone https://github.com/raphaelameaume/fragment.git

# Move to the root of the repository
cd fragment

# Run the command line locally
node ./bin/index.js examples/shape-2d.js --dev

# or from your sketch folder
node [path-to-root]/bin/index.js sketch.js --dev
```

> The `--dev` flag only enables Vite `info` logLevel, helpful for development. Otherwise it will work the same as when you're running from the npm package.

Alternatively, you can tell npm to point the `fragment` command to the newly cloned folder.

```
# at the root of the repo
npm link
```

You should be able the command as before, only this time it will point to the repository instead of the globally installed package.

```bash
fragment sketch.js
```

If that's not the case, try to uninstall `fragment-tools` globally first, make sure the `fragment` command is not found anymore, then retry to link the project from the root of the repo.

## Credits

- [Vite](https://vitejs.dev/)
- [Svelte](https://svelte.dev/)
- The font used for display is the [JetBrains Mono](https://www.jetbrains.com/lp/mono/).
- Icons are from [Iconic](https://iconic.app/)
- A special thanks to [Matt Deslauriers](https://www.mattdesl.com/) for [canvas-sketch](https://github.com/mattdesl/canvas-sketch) and his multiple projects around generative-art tools.

## License

See [LICENSE.md](./LICENSE.md) for details.

---
_Source: https://npm.io/package/fragment-tools · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
