Migrate `.p5-config.json` to a versioned unified schema to support template collections

[SableRaf]

While thinking about adding support for template collections (local or remote directories containing multiple p5.js templates), I ran into a limitation with the current .p5-config.json format, which implicitly assumes it is describing a p5.js project, and was not designed to be extensible in that way.

I’d like to migrate .p5-config.json to a more robust, versioned, and unified schema that can explicitly describe whether a directory is a p5.js project, a template collection, or another kind of entity in the future.

Since create-p5js was released very recently and does not have much downstream usage yet, this feels like the right moment to clean this up and make the config extensible and future-proof.

Usage

There is no change to the CLI interface. However, when using --source or --template, create-p5js will look for a .p5-config.json file and check whether it describes:

• a create-p5js project (allowing configuration or updates), or
• a template collection (allowing the user to pick a template from a list)

Proposed schema

Note: the schema intentionally aligns on field names (title, description, instructions, tags, license, engineURL) with the OpenProcessing API. Since OpenProcessing already defines a widely used sketch metadata format, it seems worth aligning where possible, rather than inventing a parallel vocabulary. Tool-specific fields (delivery, p5Mode, typeDefs) remain create-p5js specific.

Project

{
  "schemaVersion": 1,
  "kind": "project",
  "meta": {
    "createP5jsVersion": "0.2.3",
    "lastUpdated": "2025-12-20T17:34:43.958Z"
  },
  "project": {
    "title": "My sketch",
    "description": "A simple p5.js sketch exploring noise and motion.",
    "instructions": null,
    "tags": [],
    "license": "cc0",

    "language": "javascript",
    "p5Mode": "global",
    "delivery": "cdn",

    "p5jsVersion": "1.3.0",
    "engineURL": "https://cdn.jsdelivr.net/npm/p5@1.3.0/lib/p5.js",

    "typeDefsVersion": null,
    "typeDefsURL": null,

    "isTemplate": false
  }
}

Template Collection

A collection can either infer templates from subdirectories or define an explicit list of templates with metadata for display and filtering.

{
  "schemaVersion": 1,
  "kind": "collection",
  "meta": {
    "createP5jsVersion": "0.2.3",
    "lastUpdated": "2025-12-20T17:34:43.958Z"
  },
  "collection": {
    "templatesDir": "./templates",
    "defaultTemplate": "starter-template",
    "include": null,
    "exclude": ["node_modules", ".git", ".DS_Store"],
    "templates": [
      {
        "label": "Hello p5.js",
        "info": "A simple starter template",
        "path": "chapter_01/starter-template",
        "id": "starter-template",
        "order": 1
      },
      {
        "label": "p5.js 3D",
        "info": "A p5.js WebGL starter template",
        "path": "chapter_01/webgl-template",
        "id": "webgl-template",
        "order": 2
      }
    ]
  }
}

Notes:

• If templates is present, it defines the authoritative list and order of templates.
• If templates is omitted, templates are inferred from subdirectories of templatesDir.
• If id is ommited, the IDs are inferred from folder names.
• label and info are used for CLI display only. They can be different from the title and description property of the project.

Migration from the current format

Proposed approach

Continue to support the legacy schema, but migrate projects to the new format when running --update, with a short informational log.

Mapping

The current unversioned config:

{
  "version": "2.1.2",
  "mode": "cdn",
  "language": "javascript",
  "p5Mode": "global",
  "typeDefsVersion": null,
  "lastUpdated": "2025-12-20T17:34:43.958Z"
}

Will be treated as a legacy project config and mapped as follows:

• version → project.p5jsVersion
• mode → project.delivery
• language → project.language
• p5Mode → project.p5Mode
• typeDefsVersion → project.typeDefsVersion
• lastUpdated → meta.lastUpdated
• meta.createP5jsVersion → set to the current CLI version

Future work (speculative)

Support for Processing’s sketch.properties for compatibility with the new p5.js mode