Distributing custom builds

@raclim

Topic

One of the things we designed into p5 2.0 was a module structure so that it would be possible to built p5 without, for example, the WebGL module at all. Although this system is in place, we still haven't decided how best to give that functionality to users.

Some ideas:

We could package (minified?) versions of each module, so that you could have a multi-file p5 setup, and easily comment out the script tags for the ones you don't need
- These could be toggled on and off in something like the p5 web editor's version picker ui (cc @raclim, if you have any thoughts!)
We could make a script in the p5 repo where you specify which modules to include (or which to omit?) and then document that process somewhere
We could maybe provide a web tool to do the above for you, e.g. on the download page on the p5 site. We could give you some checkboxes for modules to include, and then make a build for you that includes those.
- Depending on how many options there are, we could pre-compute all of these at publish time so that each combination maps to a jsdelivr URL
- If that's not feasible, we maybe have to do a build for you, which could mean having a serverside thing for this, which has other costs to consider

Yes, this would be great. I am using p5 to animate a logo on a website. the minfied version is 1mb, which is steep for the logo

@davepagurek

Thanks @davepagurek! Quick thought: How about add-on libraries? I seem to remember some discussion of a possible web-editor feature that'd make it easier for users to incorporate them.

Whatever user experience we want to aim for, maybe it'd make sense for it to be designed so that add-on libraries could be added just as easily as main p5 modules, but maybe with some way of distinguishing them (e.g. as an indication of stability, etc.)?

I guess add-ons can now use the same system as main p5 to add modules, but if those were to be incorporated into the custom-build process that users go through, that might affect the feasibility of some of the approaches you've outlined?

That definitely could work! Each module of p5 is already structured as an add-on, so if we're also planning on adding some more structure to addon imports, we could do something similar for core modules if we want.

(Just my current thoughts:) Moving toward more add-on modularization seems productive, though I think FES support in add-ons would be a requirement (it's planned). In terms of increasing access, there's 2 benefits here:

reducing size - support wider array of connections.
beginner-friendliness - make it easier to navigate and include p5.js community libraries

However, the downside to beginner-friendliness is that initially I think this could be a bit extra friction to start with; though I think one of the benefits of modularizing via add-on libraries as suggested above is that it can create an easier on-ramp to the rest of the ecosystem.

While the comment-out-able list of scripts and checkboxes make a lot of sense for the website and the editor, maybe it's possible for the p5.js Editor to also "behind the scenes" include/exclude (by commenting out) unused scripts during editing, and then highlight that these are manageable checkboxes when share/download happens? This kind of proactive management opens another set of its own challenges, but I'm trying to think of ways to address the underlying needs (p5.js should be much smaller to import in many cases, but it should still be very easy to get started with).

(Including for context- There have been prior discussion of reducing bundle size via tree shakeability by design:
#5740 #7014 #4127 - however from these conversations, this looks like a major undertaking that is right now our of scope, but correct me if I'm wrong please.)

One of the goals I'd want is for p5.js is to be able to run the build in cloud environment like in Cloudflare Workers then the users will be able to choose which modules to include then it will run the build to create the build they want. One of the things we need to define is which are the core modules that all modules need to have then we can eventually have a cloud sevrice that build this on demand.

I believe Rollldown is on this path and would like to see more experiment on this in general.

I'm putting something together at the moment that will move towards the idea(s) of custom builds here, it will take some time to finish though as there are still many things that I need to disentangle within the source code. I'll summarise the goal as I understand it here.

Release individual modular build, eg. p5.core.js, p5.image.js, p5.math.js etc, which can be included in individual script tag to pick and choose which modules to include. Including all modules will be functionally equivalent to including the standard p5.js release. This way specific unused modules can be excluded where not needed to save on file size while having a familiar workflow for including modules (ie. in the same way as how addon libraries are included). Will also try to build some peripheral functionality to identify potential missing modules that the user should include.
A tool, either as a in repo CLI tool or as a web app, that can dynamically build a custom version of p5.js that only includes the modules needed.

Notably, ESM usage and user's own custom build through including ESM package won't be in scope for this as that is technically already release, although still need more comprehensive testing and fixing. There is also technically more flexibility with ESM usage since instead of including whole modules (ie. individual folders within src/) it can include individual library files if needed.

Another thing is to decide what to include in p5.core.js which is the part that is mandatory to include or the other modules won't work. There is a balance to be reach in terms of minimalism of the core and basic functionalities out of the box. Currently in my WIP, the core includes the Color module, Accessibility module, FES module, and Core module, the last of which includes Renderer2D which may or may not be desired.

There are some refactoring to do before there are something that can be used but I'll share any progress as I go along.

I have a proof of concept available in #8061 which provides a script rollup.modules.js that builds all the modules into individual files that can be included selectively with script tags. The functionalities mostly work with the occasional error message because of missing bits that may be expected in a full build. I haven't tried it but it should be the case that including all of the module files as script tags on a HTML page should be functionally equivalent to including the full p5.js library tag itself, although I can imagine possible edge cases where it may not be fully the same.

Some problems still remains though:

The interdependency issue that is causing some errors mentioned above will need some refactoring, eg. including the image module it expects the existence of the webgl module even if it does not use those feature. We probably need to make it more conditional.
The final build sizes of individual module is quite large, just as comparison the core module consisting of core, accessibility, friendly_errors, and color, is 699.4 kB minified while the current p5.min.js is 903.4kB. Including all modules or even just a number of larger modules will already be larger than p5.min.js because another problem is that some modules will be included multiple times because of interdependency.

Here's a zip version of the build for testing if needed: p5.modules.zip

I'm thinking in addition to sorting out the interdependency issue as much as possible (if even possible), maybe a different approach should be considered. What I may try instead is a build (and cache) on demand CDN service that runs the build with requested modules specified by URL queries so that it won't include the same modules multiple times, it only takes one network request, and would be able to treeshake on build.

ie. A build server that when a request of something like GET https://cdn.p5js.org/lib/2.1.0/p5.modules.js?modules=core,image,shape is made, will build a combined file with only those modules and serve it. The build results will also be cached so the next time someone also tries to get that combination of version and modules, the same file will be returned.

@limzykenneth

@limzykenneth

on demand CDN service that runs the build with requested modules specified by URL queries so that it won't include the same modules multiple times, it only takes one network request, and would be able to treeshake on build. ie. A build server that when a request of something like GET https://cdn.p5js.org/lib/2.1.0/p5.modules.js?modules=core,image,shape

That sounds like a great next step. In terms of caching, though, maybe we can start with making some specific combos cached/available (like GET https://cdn.p5js.org/lib/2.1.0/p5.modules.js?modules=core,image,shape) and others available for download in some way that is straightforward, but potentially rate-limited (do you think it makes sense to rate limit on demand builds at least to start, or am I overestimating the load here)? So the service is not necessarily caching every possible combination, and also not doing unnecessary builds.

(As a potential future extension, definitely out of scope here, do you think a finer-grained version would also work? Ie, specifiying even at the level of specific functions in query?)

@ksen0

@ksen0 The build of any specific requested combination of version and modules will only need to be done once, so the very first request to a non-cached server may take a couple seconds. Once built, the version will be cached with the version and modules used as key so next time it is requested, it will just serve from cache.

The cache (at least the root level one) will likely be backed by a S3 like storage which including gzip will likely not take up a lot of space. Bandwidth with Cloudflare is free so there's no limitation there as well.

The technical implementation is a bit blocked at the moment though since I still haven't been able to figure out how to get Rollup running in a worker environment.

A finer grained version may work but we need to disentangle a lot of the internal cross dependency while also balancing code reuse. It is going to be a bit ways off at the very least I think.

Thanks everyone for this discussion

I think modular builds would be a big win for p5.js, especially for users who just need a small subset of the functionality.

From a user perspective, I see two main benefits :

File size : For simple projects like logos, banners, or teaching demos, downloading the full ~1MB minified build feels heavy.
Beginner friendliness : Having a clear way to include only the modules you need (either through script tags or a CDN query parameter) would make it easier to onboard new learners without overwhelming them.

The on-demand CDN build idea sounds especially promising since it avoids duplicate modules and can leverage caching. Precomputing common combinations (e.g., core+image, core+webgl) might help balance performance and server load.

One question I have :---- could this system be designed to scale with "community add-ons" as well, not just core modules? It seems like the same approach could apply there, and that would make the ecosystem feel more unified.

Overall I’m excited to see progress here, and happy to test smaller builds once a prototype is available!

@yuvrajnode

@yuvrajnode It should be possible for this custom build system to also work with add-ons provided they follow some convention required for a build to succeed. This can definitely be explored somewhere down the line.

I've shared this with maintainers internally shortly before but to share more publicly, I have built out a proof of concept of the custom on demand build server idea and it is live at https://p5js-custom-build.limzykenneth.com/. To use it the URL there are a few possible URL path (where [version] is the version number from 2.0.1 and above:

https://p5js-custom-build.limzykenneth.com/[version]/p5.js - The full p5.js build
https://p5js-custom-build.limzykenneth.com/[version]/p5.min.js - The minified p5.js build
https://p5js-custom-build.limzykenneth.com/[version]/p5.[module].js - Individual module build, for example to get the math module of 2.0.5, use https://p5js-custom-build.limzykenneth.com/2.0.5/p5.math.js. The color module is not present because of a bug in p5.js releases at 2.0.5 and prior but will be available on future release.
https://p5js-custom-build.limzykenneth.com/[version]/p5.custom.js - The custom build where specific modules can be included with the ?modules= URL query. By default core, accessibility, and friendlyErrors modules are included whether they are specified or not. To get a custom build with the required modules above plus the math, io and events module for example, the URL will be https://p5js-custom-build.limzykenneth.com/2.0.5/p5.custom.js?modules=math,io,events.

Important notes

This is at a proof of concept level, all elements including URL, build artifact, defaults, etc, can all change at a later stage. Do not rely on it for any production application but do test it out where possible and report any issue to the source repo here.

The build artifacts themselves likely need additional rounds of optimization to get things to a stage where it is good to use (eg. the current minified build is noticeably larger than the production minified build), this is a known issue and will need to be worked on.

While there are extensive caching being used, this should not be rely on completely in the same way as a CDN because the build artifacts are not guaranteed to be static, all other aspects should behave similarly or identically to CDNs however.

Setup

There are two parts to this custom build server setup.

A node.js build server that builds the library on demand based on the URL path and queries.
A Cloudflare Workers edge worker that handles all the caching.

The node.js build server runs Rolldown to build the library from NPM installs of the different supported versions of p5.js (P.S. Rolldown is in this particular use case is 15x faster than Rollup to do the bundling, basically making this proof of concept possible, definitely recommend). The node.js build server is hosted on Google Cloud Run.

The Cloudflare Worker fronts the node.js build server so in deployed state, all requests reaches the Cloudflare Worker instance first and when all caches missed, the worker will forward the request onward to the node.js build server on Google Cloud Run before returning and caching the results. The cache is defined on two layers:

An object storage (Cloudflare R2) that saves all built artifacts received from the node.js build server under replayable keys, ie. if a p5.custom.js build uses the same set of modules, it can be retrieved from object storage directly instead of going to the build server for a from scratch build.
A network level cache that caches the response for a long amount of time as well as instructing any downstream cache (including browsers) to cache the response.

With this two level cache, the effect is that all built artifacts will only be generated once, after that all requests will either hit the network layer cache or if that has expired or not exist, hit the object storage cache which won't be cleared out (unless I do so deliberately). While the Rolldown build on the node.js server is very fast (around 300ms), it still takes time where as retrieving from cache should be around the 100ms mark if not less; Google Cloud Run also does not keep the build server hot all the time so sometimes the first request to a build may take a few seconds while the node.js instance spin up before running the build. The more requests hitting only Cloudflare Workers and not node.js the better.

While the ideal setup is to not have the node.js layer, I couldn't quite get Rolldown to work on Cloudflare workers (the WASI layer is not quite generic enough) but if that becomes possible in the future, the whole thing could be even faster.

Next steps

As mentioned this is a proof of concept and should be considered alpha. I still need to get a few things in p5.js itself including #8061 sorted for further improvements. I also plan to create a simple web page on the root domain to provide a GUI for generating relevant links. Things are by no means stable and further down the line the app and deployment itself may also move so definitely to try it out and test how it goes but don't rely on it for anything important, while sending any issue report to the repo or tag me directly.

I did a small comparison with three js since it's a really good example of modular subsystems and here's what I have found:

in three js all subsystems export their own classes instead of re exporting or patching the same classes exported by the core system.
internally the subsytems uses some basic abstractions of the core system maybe basic rendering of ctx or the webgl api
users can import the plugins from three js whenever they want, let it be in their sketches or using only a couple of submodules seperatedly
three js is intentionally designed to support external or community modules since it is modular, i think we can also achieve this if we make it more modular

@kitlord

@kitlord The design of Three.js is very different from p5.js which means the pattern used there may not apply. The intended audience is also rather different. However it is also already possible to import specific part of p5.js modularly.

https://p5js-custom-build.limzykenneth.com/ is now more or less working as intended. There is also OpenAPI documentation available at https://p5js-custom-build.limzykenneth.com/openapi.json plus GUI at https://p5js-custom-build.limzykenneth.com/scalar.

I've closed the build script PR as I think this build server approach is more accessible and doesn't add complexity to the build in the repo. If there is interest in the build script in the repo itself, it would be good to know some specific use case.

Once there is a bit more capacity, we will move the build server off of my server and onto a more official link. There are also still some work to be done as next steps documented in the repo.

Navigation Menu

Repository navigation

Distributing custom builds #8003

Topic

Important notes

Setup

Next steps

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Distributing custom builds #8003

Description

Topic

Activity

alexf77 commented on Aug 4, 2025

GregStanton commented on Aug 6, 2025

davepagurek commented on Aug 6, 2025

ksen0 commented on Aug 7, 2025

limzykenneth commented on Aug 7, 2025

limzykenneth commented on Aug 18, 2025

limzykenneth commented on Aug 29, 2025

ksen0 commented on Sep 2, 2025

limzykenneth commented on Sep 3, 2025

yuvrajnode commented on Oct 3, 2025

limzykenneth commented on Oct 3, 2025

limzykenneth commented on Oct 22, 2025

Important notes

Setup

Next steps

kitlord commented on Mar 6, 2026

limzykenneth commented on Apr 4, 2026

limzykenneth commented on Apr 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions