Generator-p5harmony NPM

generator-p5harmony

Yeoman generator for p5.js with webpack, dev server and ES6 through babel

This generator is extended from p5-webpack by Jannik Portz

https://github.com/janizde/p5-webpack-yeoman-generator

Installation

First, install Yeoman and generator-p5-webpack using npm (we assume you have pre-installed node.js).

npm install -g yo

npm install -g generator-p5harmony

Then generate your new project:

yo p5-harmony

Features

Webpack setup including dev server and build process
ES6 support with babel
Automatic installation of p5.dom and p5.sound if desired
Boilerplate sketch in either Instance mode or Global mode
assets directory to put any assets like audio, images into, which is served by the dev server and bundled in the build process

p5 Libraries

The generator currently supports all of the official p5 libraries (i.e. p5.sound). However there is no guaranteed support for community contributed libraries, as many of them are not available on npm or are not prepared for the use with a module bundler.

Note: Previous versions of this generator offered to include the official library p5.dom which became part of the p5 core. Hence, this option has been removed from the generator dialog and will be enhanced with more options soon.

Babel presets and plugins

Previous versions of this generator included stage-0 plugins to make use of next generation JavaScript features. Since version v0.2.0 only the preset-env preset is shipped with the template and selects language features based on the browserslist entry in package.json. Plugins for rules of other stages have to be added manually. Options to include polyfills from core-js and regenerator-runtime will be included in a future version.

Dev server

The dev server builds your whole project through the webpack build pipeline and keeps the generated artifacts in its memory (bundled files are not saved to your disk). It automatically detects when something in your files has changed, builds the changed code with webpack and automatically reloads the browser window.

You can change the port on which the HTTP server listens and more dev server related options in the webpack.config.js.

NPM commands

npm start: Runs the dev server and opens the project in your standard browser
npm run build: Builds the whole project and saves the resulting bundles in the dist directory
npm run clean: Cleans out the dist directory

Project structure

Directory Tree

your-project

|- assets [1]

|- src

| |- index.html [2]

| |- index.js [3]

| |- sketch [4]

| |- index.js [5]

|

|- package.json

|- webpack.config.js

Description

| Number | File | Description |

| -----: | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| 1 | assets | assets directory that will be served by the dev server as /assets. Put any required media like audio or images inside this directory and reference it in your sketch as /assets/my-file.jpg |

| 2 | src/index.html | HTML template. <script> tags for all bundles will be injected automatically by html-webpack-plugin. |

| 3 | src/index.js | Application entry point. Contains bootstrapping and imports of modules. Do not put your actual sketch code here. |

| 4 | src/sketch | The source directory of your sketch. Place all of your custom code in this directory. |

| 5 | src/sketch/index.js | Entry point of sketch. Contains bootstrap sketch based on the selected sketch mode |

| 6 | package.json | Your package information. Add description and other fields as you like. |

| 7 | webpack.config.js | The webpack configuration of the project. |

Sketch Modes

Sketches can either be run in Instance or Global mode. The generator bootstraps an example sketch based on the option you have selected.

You can read about the different modes in the p5 documentation

Instance mode (recommended)

It is recommended to use Instance mode with this generator as it complies best with the CommonJS module pattern. With Instance mode your sketch lives in its own portion of the project and does not operate in the global namespace.

When creating a project in Instance mode, you will find a bootstrapped sketch function in the src/sketch/index.js file. This file (module) must export a sketch function as the default export. The sketch function receives an instance of p5 as its first and only parameter. All of the p5 functions are available as members of this instance. Also, all of the p5 hooks like setup, draw or mousePressed must be set on the p5 instance itself. A very basic sketch would be:

export  default  sketch(s) {

let bgColor;



s.setup = () => {

bgColor  =  s.color(s.random(255),  s.random(255),  s.random(255));

};



s.draw = () => {

s.background(bgColor);

s.fill(s.color(255,  0,  0));

s.ellipse(0,  0,  10,  10);

};

}

Global mode

Though Global mode is the mode that most p5 tutorials and projects refer to, it is not so straight forward to integrate it with the CommonJS module pattern.

While for a standard p5 setup it's enough to specify your hooks by just defining a function in the global namespace (e.g. function setup() {...}), in CommonJS modules there is no real global namespace.

When creating a new project in Global mode, you will find a bootstrapped sketch in Global mode in the src/sketch/index.js file. Instead of just defining the setup, draw etc. functions you will additionally have to export these functions. A code snippet in the src/index.js file attaches everything that is exported from the actual sketch file to the global window object, so p5 works as expected. Please also note, that everything else you export from the sketch file will also be attached to the global window object. So please make sure you only export hook functions from your sketch file.

The above example in Instance mode would look like this in Global mode:

let bgColor;

export function setup() {
  bgColor = color(random(255), random(255), random(255));
}

export function draw() {
  background(bgColor);

  fill(color(255, 0, 0));

  ellipse(0, 0, 10, 10);
}