README.md

Fragment

A web development environment for creative coding

fragment provides a simple API to work with <canvas>.

Features

• Multiple rendering modes: Canvas 2D, p5.js, three.js, WebGL fragment shaders
• Built-in GUI from sketch files
• Export <canvas> to images (.png, .webm, .jpg) or videos (.mp4, .webm, .gif) on the fly
• Hot shader reloading & glslify support
• Interactive sketches using triggers
• Static build for production deployment

Installation

With npx

npx fragment-tools sketch.js --new

Installing globally with --global

npm install fragment-tools --global

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

fragment sketch.js --new

Installing locally

npm install fragment-tools
npx fragment sketch.js --new

Usage

# create a new directory for your sketches
mkdir sketches

# move into that folder
cd sketches

# create a sketch from a template
npx fragment-tools ./sketch.js --new --template=2d

Learn more about the available flag options in the CLI docs.

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.

export let props = {
  radius: {
    value: 10,
    params: {
      min: 4,
      max: 30,
    },
  },
};

export let update = ({ context, width, height }) => {
  // draw background
  context.fillStyle = '#000000';
  context.fillRect(0, 0, width, height);

  // draw circle
  const radius = props.radius.value;

  context.fillStyle = '#0000ff';
  context.beginPath();
  context.arc(width * 0.5, height * 0.5, radius, 0, 2 * Math.PI, false);
  context.fill();
};

Learn how to write your own sketch by following the Getting started guide, reading the API docs or the examples.

Contributing

If you find issues, please file one with details on how to reproduce it.

Feel free to reach out on Twitter if you want to discuss the project.

Running it locally

# 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.

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
• Svelte
• The font used for display is the JetBrains Mono.
• Icons are from Iconic
• A special thanks to Matt Deslauriers for canvas-sketch and his multiple projects around generative-art tools.

License

See LICENSE.md for details.