p5.js 2.0 Update: Beta, Timeline, and Compatibility Addons

[ksen0]

Hi!

I’m Kit, and I’ve joined the Processing Foundation recently as project lead for p5.js! I am so excited to be part of this amazing community, and to start helping bring the vision of p5.js 2.0 to completion.

In this update, I want to share our current thoughts about compatibility. (Even as p5.js 2.0 becomes more stable, p5.js 1.x will continue to be supported!)

Last year, we initiated the p5.js 2.0 RFC (Request for Comment) process to collectively re-envision the next major release of p5.js. Since then, many contributors have been working to make p5.js 2.0 happen.

• You can read more about the Governance Model and Decision-Making Process in the previous update: p5.js 2.0 Updates #7261
• You can find the beta release of 2.0 here: https://github.com/processing/p5.js/releases/tag/v2.0.0-beta.2 🆕

Now that the beta release is available, you can try testing out the beta! Please report any bugs you encounter to help improve p5.js 2.0. To try out the beta release:

• You can duplicate this web editor project: https://editor.p5js.org/davepagurek/sketches/wiOiYAp6P
• You can also add a script tag to this build that @davepagurek is hosting: <script src="https://davepagurek.com/stuff/p5/p5-2.0-b1.min.js"></script>

Even as p5.js 2.0 becomes more stable, p5.js 1.x will continue to be supported for at least a year. Here’s the timeline so far:

• We plan to have p5.js 2.0 finished by the end of March 2025.
• Up until August 2026 (next year!), the p5.js Editor will still default to p5 1.x, with an option to switch to 2.0 when it is finished.

Between 1.x and 2.0, there are many additions, and some breaking changes. In addition to making p5.js 2.0 available as a library, we are working on preparing several compatibility addons that would make it possible to keep using 1.x features that are no longer part of 2.0.

• You can review the 2.0 changes in the release notes
• We’ve prepared this check-in survey about the breaking changes. This is because many users of p5.js are not active on GitHub. Please feel free to engage in the discussion here on any topic in the survey or regarding the changes - and to share the survey with p5.js users you know who might be!
• Do you have a library that depends on p5.js and you’d like to update it for compatibility with 2.0? If your library is in the directory then we are already planning to check whether the change from 1.0 to 2.0 breaks examples given by that library. Feel free to test your library out with the new release, or reach out / comment here!

What do we mean by “Compatibility addon?” If you want to use something like preload() which has been removed in 2.0, you would have to use a <script> tag to import both p5.js 2.0 and the compatibility addon for that feature. If you do that, any use of preload() just like in 1.x will continue to work. We are preparing addons for other changes, such as shape/vertex, listed here.

Thank you!

[GregStanton]

Thanks for the update @ksen0!

Question: Is there a plan for syncing the reference on p5js.org with the default version of p5.js in the web editor? For example, if the web editor defaults to 1.x until March 2026, but the reference documents version 2.0 when it's released in March 2025, then users following the reference may get unexpected errors.

I imagine there's already a plan in place for this, but in case there's not, here's an initial idea. By the time 2.0 is released, I think it will have been about nine months since the release of the new p5.js site. So, perhaps the link at the bottom of every page that reads "Looking for the old p5.js site? Find it here!" is no longer needed; it could be moved to a less prominent place on the site. In its place, there could be a link that reads "Using the new p5.js 2.0? Check out the updated site." In March 2026 when the web editor defaults to 2.x, this arrangement could potentially be flipped, with the 2.x version being the main version, and a link to the 1.x version at the bottom of every page.

In addition to alleviating confusion around the reference, this would also address conflicts relating to tutorials and examples, and to the contribute page, all of which might contain updates related to 2.0.

[ksen0]

Hi @GregStanton that's a great question!

This depends on exactly how reference is updated on the website itself. I am in the process of checking if/how it would be technically possible, but one idea would be that the URLs stay stable, and each page allows toggling between versions in a way that persists. So one possible behavior is that while the editor defaults to 1.x, and so does the site, opting in is done twice. Or, as you describe, if a user opts-in in one place, that persists in the second place (e.g., through a cookie). Depending on how a hypothetical "version toggle" might be able to work, it could be used in tutorials/examples, not only reference. If it's not possible or practical to do a "version toggle" approach, something like what you're describing makes a lot of sense.

One thing we've also been discussing is the idea of pro-actively helpful with transition from 1.x to 2.0. As I mentioned, libraries in the directory we are already planning to check whether the change from 1.x to 2.0 breaks examples given by that library, and notify those projects through an issue. It is up to the maintainers of each library whether to support 1.x, or 2.0, or both, and on what kind of timeline. I think it would be best if resources like the libraries page are also able to show which version is supported.

There are also other pieces, like the Autocomplete Hinter in the p5.js Editor, and FES, that will need to be updated to help users navigate errors related to versions. One way I'm thinking about this: if someone is starting not from the p5.js website, but from an example they found elsewhere online, and is new to p5.js, what are the possible ways that our tools can help them understand and resolve the errors?

Very happy to hear additional thoughts about all the above.

[tespin]

hi all, excited for these upcoming changes!

@ksen0 based on what you described, my understanding is that users would have 2 approaches:

Option A (independent toggles)
editor and site default to 1.x

1. user switches editor to 2.x
   • editor now uses 2.x
   • documentation still on 1.x.
2. user then switches docs to 2.x   
   • Both editor and documentation are now toggled to 2.x

Option B (linked toggles)

1. user toggles either editor or docs to 2.x
2. maybe a prompt or alert asks to confirm the switch, and both pages are then on 2.x

if i misinterpreted, please feel free to clarify! otherwise, i think both have strengths but also some tradeoffs. option A is more flexible and more explicit with the transition but introduces some cognitive load with having to keep track of which page is on which version. option B has a more consistent environment which is great for beginners, but would probably need some complex state management and can still be disruptive if there is no clear indication of versions persisting between pages.

@GregStanton's suggestions look familiar with how other popular tools have managed transitions. for example, for react's transition from v17 to v18, they made a beta version of their docs available at a new url (i think beta.reactjs.org or something). the legacy site was maintained but updated with banners and other indicators that pointed to the new docs until they finally transitioned to react.dev. i do feel this strategy is complicated in its own way with maintaining all the urls but it worked for their use case (big conceptual changes and new approaches to state and data management).

i think that p5 2.0's changes are less conceptual and more implementation, for the most part? there will definitely need to be version-specific references but the core concepts and learning pathways still feel similar. maybe we can think about a hybrid approach where the current editor url defaults to editor 1.x, but the ui includes a "Try in 2.0" button that links to something like editor.p5js.org/v2. for the reference docs, i believe i've seen other tools use a select / dropdown menu for global version selection, or if we want to limit to only the changed functions, their specific entries can have a 1.x / 2.x toggleable switch as part of the editor ui, which could also be used in the tutorials / examples pages. this way editor 1.x remains stable during the transition with a clear 2.0 opt-in, and the docs are flexible depending on what the user chooses.

other thoughts: a migration guide would be really helpful esp for users or libraries, possibly some kind of version detector in the code editor, a v1 to v2 converter ...

[limzykenneth]

New Beta Release

Version 2.0.0-beta.2 is now released with a few fixes and getting things up to date with 1.x.

I'll create a release on NPM as well so people can try out using p5.js directly from NPM with ESM and the beta being available on jsdelivr.

Edit: JSDelivr links

• p5.js - https://cdn.jsdelivr.net/npm/[email protected]/lib/p5.js
• p5.min.js - https://cdn.jsdelivr.net/npm/[email protected]/lib/p5.min.js

[calebfoss]

Welcome, @ksen0! I'd like to check in about accessibility in p5 2.0.

Last year as part of the project funded by @sovereigntech, I proposed some possible changes for improved accessibility in #6992. I see that this is listed as a high priority in the project, but I'm not seeing any updates on implementation. Will any of them be included in 2.0? Will there be any other features targeting accessibility?

One of the issues I mention in that doc is #6126, which has been open for over a year and still appears to be an issue in the 2.0 beta.

To commit to the project's mission, and especially since donations and unpaid labor are solicited while highlighting accessibility as a priority, I hope to see p5 and its website catch up on accessibility issues before adding new features like these.

Beyond my previous suggestions, I would love to see accessibility testing performed to get feedback from people with disabilities on both the experience of creating with p5 and engaging with content created using it. I think this would bring up many new directions for development that would prioritize accessibility. My suggestions are limited by my perspective as an able-bodied person.

[ffd8]

Quick chime in to request that v2.0 try even harder to be v1.0 backwards-compatible. This seems like a big accessibility point – how many learning resources, materials (tutorials, videos, handouts), examples, etc will stop working due to breaking changes? Just two are mentioned for now, ie removing preload() and renaming functions like curveVertex() (just as a stand in, for potential others) – when it could be an update with a 'yes, and...' mantra, v1.0 and much more. Of course it's inherent in the version naming, that 2.0 suggests breaking changes, but backwards compatibility could be more of a pre-requisite for these new features. Ie, it was mentioned on another issue, adopting techniques to allow either preload or the await technique for advanced users (somehow q5 has a technique). Such as continue support for curveVertex() while adding a splineVertex() with more functionality. The docs can point people towards the newer, extended workflows, but keep the previous work (that goes beyond sketches) still relevant. As seen in other threads, it opens up not exciting forks or fractures in the editor, docs, tutorials, libraries, etc etc to constantly decide for A or B due to deprecated functions.

I just read the post regarding the pendingcompatibility add-on js file, which makes me wonder how big/small would it be and if it could be embedded within 2.0, having the 1.0 (existing way for past 10+ years) as default, with the newer approaches and breaking features, becoming an opt-in change? Maybe I'm so focused on making as-few/no breaking changes as possible because of the community that p5 strives to be available for, making sure it's always the easiest/simplest/beginner-friendly approach, even at the sacrifice of performance/advanced-features etc.. it's an amaaazing swiss army knife that continues to get more and more capable, and has very rarely broken previous features with the addition of others. I'm also likely fixed on this as an educator who has seen how great the current workflow is and sees some suggested changes (also for the new p5.sound) as setting the entry level a few steps higher than they were.

On a personally affected note, tested within P5LIVE (the tool I develop since 2019 for the live-coding community), and found it breaks almost all demos (and my sketches), with the following error in the console. I also tried excluding the p5.sound lib to see if that's the issue – but perhaps you've made a big change in how mouseX/mouseY/pmouseX/pmouseY/frameCount work, or that they are now tucked behind a const context? P5LIVE overrides p5.js' frameCount and mouseX/Y etc - in order to provide a continuous and smooth transition behind every reloading of the sketch within an iframe (I call it 'softCompile') – imagine a circle traveling across page with frameCount%width, that each time the code changes and reloads, that circle doesn't jump back to 0.. I'd argue this is also an accessibility feature, as it accompanies other features to prevent flashes that could be triggering when viewing and editing sketches fullscreen. But besides that, it's crucial to override these variables when performing for an audience with p5.js, so that things aren't constantly resetting on every change.

Hmm also just disabled all overriding of global vars and still can't get even a basic circle sketch to work beyond the single first frame (remains static, frameCount doesn't grow.. somehow frozen). Happens while only adding a circle(frameCount%width, mouseY, 50) within the draw(). This can be experienced in a demo here that manually overwrites the version of p5.js. Nothing in the console suggests why it doesn't get beyond the first iteration of the draw() function. Adding loop() etc doesn't have any effect...

[limzykenneth]

@ffd8 Thanks for chiming in here. I want to give a bit of context from my perspective and give a bit of reasoning behind the changes. I'm mostly speaking personally here.

For p5.js 2.0, the main breaking changes that we currently see affecting backwards compatibility with existing sketches are preload and bezier vertices. Accordingly, the compatibility addon which is already implemented here patches these features where needed. If there are any additional breaking changes, that's what we want people testing 2.0 beta to open issue on, it might just be a bug and not a breaking change, or we might have overlooked it and can implement it into the compatibility addon, so I really encourage that. The compatibility addon does not add significant file size that a sketch needs to load, especially compared with p5.js itself.

Creating a major semver release is a very deliberate choice to break backwards compatibility, to be fully backwards compatible will defeat the purpose of doing a major semver release, but that's honestly a bit backward in terms of motivation. The main goal of 2.0 is to bring p5.js up to the standard of modern Javascript and Javascript ecosystem in general, preload is an artifact of the limitations Javascript had in the early years of p5.js's development it was created because there was no other viable option, but now we have a viable option that brings p5.js loading syntax closer to what a non-asynchronous language including Processing would be doing. I want p5.js to be a stepping stone towards using other things in the Javascript ecosystem, and the rest of the Javascript ecosystem does not have preload. I have a longer write up for this part and other parts of the changes that I'll publish soon.

Stepping back a bit, I understand there will be existing materials that will have compatibility issue with p5.js 2.0, I have such materials myself and I know this will be a thing when even before p5.js 2.0 is a well-formed idea. If p5.js is bound to never break backwards compatibility forever because of existing materials, I see that as way too restrictive in terms of what p5.js can be. Keeping breaking changes fully around in p5.js 2.0 (such as bundling the compatibility addon into 2.0 itself) means that the next opportunity to make a clean break can only happen with p5.js 3.0 and we will be back in the same situation and discussion here, except having even less of an argument to make this clean break. The entry level for p5.js 2.0 and consequently materials for entry level should be the same all the way until loading data, changes to bezier vertex are done to reduce non-intuitiveness making drawing curves easier to use, other larger changes are either internal or addition in a non-breaking way. I don't immediately see where that entry level has been a few steps higher so I would like some clarifications here.

Mentioned at the top post here, there is a transition plan, p5.js 1.x is not disappearing as soon as p5.js 2.0 is released and we are not abandoning 1.x, bug reports will still be reviewed and fixed just no new feature will be added. p5.js 2.0 is not even going to be the default version used by the p5.js web editor when p5.js 2.0 is released. You can also see in discussions above that we are looking into how to transition the documentation with the view that a lot of people will still be using 1.x. It is planned to have a least a full year for the community to transition with our support before any major switch is done (tentative time to transition has been pushed back from March 2026 to August 2026). If there are incompatibilities in terms of transition plan and timeline, let us know and we can work out something that can work. We are already in the process to testing p5.js 2.0 with known addon libraries to see to what extend they need to update if at all. We have been in touch with OpenProcessing to coordinate a transition plan that they would like to adopt.

I'm more than happy to help look into P5Live and its requirement to work with p5.js 2.0 and I would suggest opening an issue for that.

[ffd8]

@limzykenneth many thanks for your thorough reply! I'll try to get more familiar with the upcoming features to appreciate why breaking changes were required. p5.js has been amazingly stable (thanks to so much hard work and PRs from the community!), while libraries have brought those deeper features for advanced users – that I would have been personally happy for 1.0 to reach 1.999.... great to hear the org has been working with OpenProcessing to coordinate changes, and I'll do the same as a separate issue. Guess it's also time to finally implement a version selection for individual sketches...

In terms of 'a few steps higher' for the entry level beginner – this switch from synchronous loads to async/await, opens a pretty huge can of complicated worms. Just read a few StackOverflow threads and youtube vids to try and get the concept myself (not using it at all, even if I should) – trying to digest to teach a student who codes for the very first time, why they need to async/await their loaded picture of a fish, will likely require some 'just follow me' for a long while. Moments I also wonder about, ie Is the function setup() without async if no assets are loaded? Previously it was really easy to describe the waterfall of preload() assets to be ready by the setup() that happens once, then are ready to use in your draw(). Of course once getting into heavy datasets, videos, big images, etc – we don't want the sketch/website to hang, but it could be good at the start to appreciate what you're asking the browser to load. Probably just need to find the right analogies to keep this as simple as before and hope students don't walk into the various gotcha moments promises can introduce. Very much looking forward to your writeup diving into why/whynot preload.

[limzykenneth]

@ffd8 Honestly I actively avoided async/await myself for the first few years when it was available out of a sense of it being "un-javascript" or some other reason that may or may not be justified. I've since came around I guess and I've been using it where possible and it's relatively intuitive. It is to put it simply the attempt to make everything actually run from top to bottom as we expect it to, so at this point my view is that it is solving the same problem as preload just with Javascript itself.

Is the function setup() without async if no assets are loaded?

The rule is await must be used inside an async function. If there is no await it doesn't matter if setup is marked as async or not, it is handled the same way by the runtime.

In any case, I have completed the write up here, do have a look and let me know if I should clarify anything. It is a bit of a long read to give a fuller context, hopefully it can give you some idea around how to explain promises/asynchronicity to your students.

I'm working on other long form write up on other intermediate to advanced stuff as well, including changes to addon library structure, and will likely get around to reviewing the addon libraries you have as well. Others on the team are working on other parts of the transition including more FES messages that helps with migration in both 1.x and 2.0 so error messages can help users correct syntax from 1.x to 2.0.

[ffd8]

@limzykenneth great writeup! Definitely clears the confusion on my end and leaves me confident I can get into async/await. Plus this writeup will become required reading in future courses. v2.0 is coming, that's clear and it will cause plenty of pains while juggling both versions during the transition and it's all for the better... nevertheless my stubborn brain fails to see why this preload() hack doesn't stick around, even if it becomes an ignored and actively warned against function in future docs. Guess time will tell how long the compatibility add-on will be maintained/required or if 2.0 is where functions get flagged for deprecation and 3.0 is where it happens? Haha.. kicking the discussion 🥫 down the road 🛣️.

In terms of library contributions, the 'callback' parameter won't be disappearing on any of the load___() functions, will it? Especially when loading outside of the setup().

[limzykenneth]

@ffd8 Yes, callbacks will still be supported the same. There's also a semi-secret functionality which is that the callback can also act as a filter for the promise resolve value, ie. what you return from the callback becomes the value the promise resolves to after loading is done. This opens up some potential extension possibility where an addon can call loadJSON() then assemble the data received to return as a class instance object for example.