diff --git a/README.md b/README.md
index aead7ae0da..21f63ec68f 100644
--- a/README.md
+++ b/README.md
@@ -10,23 +10,23 @@ We are a community of, and in solidarity with, people from every gender identity
Learn more about [our community](https://p5js.org/community/) and read our [Community Statement and Code of Conduct](./.github/CODE_OF_CONDUCT.md). You can directly support our work with p5.js by [donating to the Processing Foundation](https://processingfoundation.org/support).
-Stay in touch with Processing Foundation across other platforms:
+Stay in touch with Processing Foundation across other platforms:
+
- [Instagram](https://www.instagram.com/p5xjs)
- [Youtube](https://www.youtube.com/@ProcessingFoundation)
- [X](https://x.com/p5xjs)
- [Discord](https://discord.com/invite/esmGA6H6wm)
- [Forum](https://discourse.processing.org)
-
## Using the p5.js Editor π€
-Make your first sketch in the [p5.js Editor](https://editor.p5js.org/)! Learn more about sketching with p5.js on the [Get Started](https://p5js.org/tutorials/get-started/) and find everything you can do in the [Reference](https://p5js.org/reference/). You can also look at [examples](https://editor.p5js.org/p5/sketches) and remix them in the p5.js Editor.
+Make your first sketch in the [p5.js Editor](https://editor.p5js.org/)! Learn more about sketching with p5.js on the [Get Started](https://p5js.org/tutorials/get-started/) and find everything you can do in the [Reference](https://p5js.org/reference/). You can also look at [examples](https://editor.p5js.org/p5/sketches) and remix them in the p5.js Editor.
-For more information on usage guidelines for the p5.js Editor, check out the [p5.js Editor Terms of Use](https://editor.p5js.org/terms-of-use). To gain better insight into how we handle user data and data privacy, refer to the [p5.js Editor Privacy Policy](https://editor.p5js.org/privacy-policy).
+For more information on usage guidelines for the p5.js Editor, check out the [p5.js Editor Terms of Use](https://editor.p5js.org/terms-of-use). To gain better insight into how we handle user data and data privacy, refer to the [p5.js Editor Privacy Policy](https://editor.p5js.org/privacy-policy).
## Contributing π π π¨
-The p5.js Editor is a collaborative project created by many individuals, mostly volunteers, and you are invited to help. All types of involvement are welcome. To get started with contributing to the p5.js Editor, we recommend exploring the following resources in order:
+The p5.js Editor is a collaborative project created by many individuals, mostly volunteers, and you are invited to help. All types of involvement are welcome. To get started with contributing to the p5.js Editor, we recommend exploring the following resources in order:
1. [p5.js Community Statement and Code of Conduct](https://editor.p5js.org/code-of-conduct) - Read our Community Statement and Code of Conduct to understand the values that guide our community and how to participate respectfully and constructively.
@@ -34,21 +34,12 @@ The p5.js Editor is a collaborative project created by many individuals, mostly
3. [All Contributors list on the p5.js repository](https://github.com/processing/p5.js?tab=readme-ov-file#contributors) - Explore the All Contributors list to see the wide range of contributions by our amazing community!
-> **TypeScript Migration:**
-> As of July 2025, we are working on migrating the repo to TypeScript as part of the **[p5.js Web Editor pr05 Grant](https://github.com/processing/pr05-grant/wiki/2025-pr05-Program-Page)**.
-> This migration will occur in two phases:
-> 1. **Grant Work (July β October 31, 2025)** β Setting up TypeScript configuration, tooling, and starting partial migration. Contributions will be **closed** during this period.
-> 2. **Open Contribution (After October 31, 2025)** β TypeScript migration tasks will **open** to all contributors, with guidelines and tutorials available.
+> **TypeScript Migration:** We have initiated migrating the repo to Typescript as part of the **[p5.js Web Editor pr05 Grant](https://github.com/processing/pr05-grant/wiki/2025-pr05-Program-Page)**, and the repo is now open to migration contributions.
>
-> For full details, see [TypeScript Migration Plan](./contributor_docs/typescript-migration.md).
+> Please see [Typescript Migration](contributor_docs/typescript_migration.md) for migration guidelines. Please see [2025 pr05 Typescript Migration Project](contributor_docs/pr05_2025_typescript_migration/index.md) for details and technical decisions for the migration project.
## Acknowledgements π
-Support for this project has come from [Processing Foundation](https://processingfoundation.org/), [NYU ITP](https://tisch.nyu.edu/itp), [CS4All, NYC DOE](http://cs4all.nyc/), [COSA at DU](https://liberalarts.du.edu/emergent-digital-practices/open-source-arts), [STUDIO for Creative Inquiry](https://studioforcreativeinquiry.org/), [Grant for the Web](https://www.grantfortheweb.org/), [New Media Rights](https://www.newmediarights.org/), and many others.
+Support for this project has come from [Processing Foundation](https://processingfoundation.org/), [NYU ITP](https://tisch.nyu.edu/itp), [CS4All, NYC DOE](http://cs4all.nyc/), [COSA at DU](https://liberalarts.du.edu/emergent-digital-practices/open-source-arts), [STUDIO for Creative Inquiry](https://studioforcreativeinquiry.org/), [Grant for the Web](https://www.grantfortheweb.org/), [New Media Rights](https://www.newmediarights.org/), and many others.
-Hosting and technical support has come from:
-
-
-
-
-
+Hosting and technical support has come from:
diff --git a/contributor_docs/README.md b/contributor_docs/README.md
index e33bfa20ee..f1536f549b 100644
--- a/contributor_docs/README.md
+++ b/contributor_docs/README.md
@@ -1,23 +1,24 @@
# Contributor Documentation
+
This folder contains guides for contributing to the p5.js Web Editor. You don't need to know everything to get startedβexplore at your own pace! To begin, we highly recommend starting with the [Contribution Guide](https://github.com/processing/p5.js-web-editor/blob/develop/.github/CONTRIBUTING.md)!
These guides aren't exhaustive, and do not cover all the possible ways you can contribute to a project. If you have an idea for how you'd like to help and don't see a guide for it here, you're welcome to add it to the "Documents to Create" list below by opening an issue!
-
## List of Documents
-* [Contribution Guide](https://github.com/processing/p5.js-web-editor/blob/develop/.github/CONTRIBUTING.md) - A place to get started!
-* [Installation](installation.md) - A guide for setting up your development environment.
-* [Development](development.md) - A guide for contributing code to the codebase.
-* [Testing](./testing.md) - A guide for writing and running tests in the codebase.
-* [Preparing an Issue](preparing_an_issue.md) - Instructions for creating and navigating issues.
-* [Preparing a Pull Request](preparing_a_pull_request.md) - Instructions for making a pull-request.
-* [Accessibility Guidelines](accessibility.md) - Guidelines for writing code to create an accessible application.
-* [Translations Guidelines](translations.md) - Guidelines for translating the p5.js editor.
-* [Deployment](deployment.md) - A guide to production deployment, and all platforms that are being used.
-* [Release](./release.md) - A guide to creating a production release.
-* [Typescript Migration](./typescript_migration.md) - About the Typescript Migration project.
+- [Contribution Guide](https://github.com/processing/p5.js-web-editor/blob/develop/.github/CONTRIBUTING.md) - A place to get started!
+- [Installation](installation.md) - A guide for setting up your development environment.
+- [Development](development.md) - A guide for contributing code to the codebase.
+- [Testing](./testing.md) - A guide for writing and running tests in the codebase.
+- [Preparing an Issue](preparing_an_issue.md) - Instructions for creating and navigating issues.
+- [Preparing a Pull Request](preparing_a_pull_request.md) - Instructions for making a pull-request.
+- [Accessibility Guidelines](accessibility.md) - Guidelines for writing code to create an accessible application.
+- [Translations Guidelines](translations.md) - Guidelines for translating the p5.js editor.
+- [Deployment](deployment.md) - A guide to production deployment, and all platforms that are being used.
+- [Release](./release.md) - A guide to creating a production release.
+- [Typescript Migration](typescript_migration.md) - About the Typescript Migration project.
## Documents to Create
-* Software Design Principles - reference [p5.js software design principles](https://github.com/processing/p5.js/blob/eb61f7a260531d17930de3c987949558ce242d35/contributor_docs/contributor_guidelines.md#software-design-principles)
-* File Structure - An explanation of the file structure of this application.
+
+- Software Design Principles - reference [p5.js software design principles](https://github.com/processing/p5.js/blob/eb61f7a260531d17930de3c987949558ce242d35/contributor_docs/contributor_guidelines.md#software-design-principles)
+- File Structure - An explanation of the file structure of this application.
diff --git a/contributor_docs/pr05_2025_typescript_migration/images/hoverJsDocs.gif b/contributor_docs/pr05_2025_typescript_migration/images/hoverJsDocs.gif
new file mode 100644
index 0000000000..c270bdff52
Binary files /dev/null and b/contributor_docs/pr05_2025_typescript_migration/images/hoverJsDocs.gif differ
diff --git a/contributor_docs/pr05_2025_typescript_migration/images/swagger-microsite.png b/contributor_docs/pr05_2025_typescript_migration/images/swagger-microsite.png
new file mode 100644
index 0000000000..802975294f
Binary files /dev/null and b/contributor_docs/pr05_2025_typescript_migration/images/swagger-microsite.png differ
diff --git a/contributor_docs/pr05_2025_typescript_migration/index.md b/contributor_docs/pr05_2025_typescript_migration/index.md
new file mode 100644
index 0000000000..6628f08d4a
--- /dev/null
+++ b/contributor_docs/pr05_2025_typescript_migration/index.md
@@ -0,0 +1,595 @@
+# pr05 2025 Typescript Migration
+
+This is the project appendix for the **2025 pr05 Grant: Incremental Typescript Migration of the p5.js Web Editor**.
+
+## Additional Reading:
+
+- [All PRs related to the pr05 grant can be found with the `pr05` tag](https://github.com/processing/p5.js-web-editor/issues?q=state%3Aclosed%20label%3A%22pr05%20Grant%20Projects%22)
+- [pr05 grant](https://github.com/processing/pr05-grant/wiki/2025-pr05-Program-Page)
+- [pr05 grant: Typescript Migration Project](https://github.com/processing/pr05-grant/wiki/2025-pr05-Project-List#incremental-typescript-migration-for-the-p5js-editor)
+- [Intro to the Incremental Typescript Migration for the p5.js Web Editor](https://medium.com/@clairepeng94/intro-to-the-incremental-typescript-migration-for-the-p5-js-web-editor-2ffbc305c6a9)
+
+## Table of Contents
+
+- [Project Outline](#project-outline)
+ - [Context](#project-context)
+ - [Proposed Approach](#proposed-approach)
+ - [Project Timeline](#project-timeline)
+ - [All PRs](#all-prs)
+- [Summary of Outcome](#outcome)
+- [Key Decisions](#key-decisions)
+- [Summary of TS Configurations](#configuration-summary)
+- [Migration Tutorial](#migration-tutorial)
+- [Index of Migration Examples](#examples-index)
+- [Next Step Issues](#next-step-issues)
+- [Additional Reading](#additional-reading)
+
+## Project Outline:
+
+### Project Context:
+
+
+ View details
+
+- Grant period of 200h over July 1st - October 31, 2025
+- 116k lines of code within the repo, with about 30% test coverage
+- Many older technologies, tied to Node 16 (bumped to Node 18 in August)
+
+
+
+### Proposed Approach:
+
+> To set up the repo so that beginning contributors can pick up migration work as a "Good first issue"
+
+
+ Set up all config to be both TS & JS compatible
+
+- Not possible to migrate entire repo within 200h
+- Migration must also be file-by-file, so all config needs to be flexible to work with legacy JS code
+- Key technologies:
+ - Node
+ - React
+ - Express
+ - MongoDB
+ - Jest
+ - Babel
+ - Webpack
+ - ESLint
+
+
+
+
+ Set up typechecking tooling & automation
+
+
+- Global typecheck command for both the `/server` and `/client` folders
+- Isolated typecheck command for each the `/server` and `/client` folders
+- Automated typecheck on pre-commit hook
+- Automated typecheck on CICD tests
+
+
+
+
+
+ Migrate an instance of each "kind" of file a developer might encounter to provide example code to follow
+
+
+- Client:
+ - React file
+ - Plain TS file (eg. `/utils`)
+- Server:
+ - Mongoose Model --> `User`
+ - Mongoose Controller --> `User.Controller`
+ - Express Routes
+ - Plain TS file (eg. `/utils`)
+- Examples of writing tests for the above
+- Example of extending namespaced types through `.d.ts` files
+
+
+
+### Project Timeline:
+
+Click to view details by month
+
+
+ July:
+
+- Set up TS dependencies & configuration on the `root`
+ - `tsconfig.json`
+ - `tsconfig.base.json`
+ - `.babelrc`
+ - `.eslintrc`
+ - `package.json > jest.config`
+ - `webpack/`
+- Set up TS dependencies & configuration in `/client`
+ - `/client/tsconfig.json`
+ - `@types/...` for `/client` dependencies (eg. React 16)
+- Set up `typecheck` and `typecheck:client` commands in `package.json`
+- Migrate `/client/utils`
+
+
+
+
+ August:
+
+- Migrate `/client/common` with co-located types & tests
+- Migrate `/client/components` with co-located types & tests
+
+
+
+
+ September:
+
+- Set up TS dependencies & configuration in `/server`
+ - `nodemon.json`
+ - `webpack/`
+ - `/server/tsconfig.json`
+ - `@types/...` for `/server` dependencies
+- Set up `/server/types` to store all `/server` types (eg Mongoose v8)
+- Migrate `/server` components related to emailing and `nodemailer`
+- Migrate `/server/routes`
+- Migrate `/server/models/User` with tests
+- Migrate `/server/models/ApiKeys` with tests
+- Start migrating `/server/controllers/User`
+
+
+
+
+ October:
+
+- Complete migration for `/server/controllers/User`
+ - Added tests to all the methods & re-organised by sub-domain (eg. auth management) & added JSDocs for each controller method.
+- Instantiate `.d.ts` files for `express` and `jest-express` to create a custome `Express` namespace `Request.User` definition
+- Set up `/common/types` folder to
+- Migrate root redux files: `/client/store`, `/client/reducers` & `/client/persistState`
+- Migrate user preferences redux: `/client/IDE/reducers/preferences` & `/client/IDE/actions/preferences`
+- Migrate `/client/modules/Legal`
+- Migrate `/client/modules/About`
+- Migrate most of `/client/modules/User` (with exception of files related to `Collections`)
+- Clean up of previous work & documentation
+
+
+
+## All PRs:
+
+Click to view all PRs for this project:
+
+
+ Click to view all PRs for this project:
+
+
+- [pr05 Typescript #1: Set up TS dependencies in the root & client](https://github.com/processing/p5.js-web-editor/pull/3533)
+- [pr05 Typescript #2: automatically resolve imports of ts files & migrate instance of client/utils file](https://github.com/processing/p5.js-web-editor/pull/3540)
+- [pr05 Typescript #3: Migrate client/utils folder](https://github.com/processing/p5.js-web-editor/pull/3553)
+- [pr05 Typescript #4: migrate instance of react file](https://github.com/processing/p5.js-web-editor/pull/3554)
+- [pr05 Typescript Migration #5: Migrate client/common folder](https://github.com/processing/p5.js-web-editor/pull/3565)
+- [pr05 Typescript Migration #6: Initial docs on typescript migration](https://github.com/processing/p5.js-web-editor/pull/3581)
+- [pr05 Typescript Migration #7: migrate client components](https://github.com/processing/p5.js-web-editor/pull/3619)
+- [pr05 Typescript #8: migrate client/components/Menubar/MenubarSubmenu](https://github.com/processing/p5.js-web-editor/pull/3623)
+- [pr05 Typescript Migration #10: Setup Server TS Dependencies & migrate instance of server file](https://github.com/processing/p5.js-web-editor/pull/3636)
+- [pr05 Typescript Migration #11: Migrate server/routes folder](https://github.com/processing/p5.js-web-editor/pull/3643)
+- [pr05 Typescript Migration 12: Migrate server files related to emailing/nodemailer](https://github.com/processing/p5.js-web-editor/pull/3658)
+- [pr05 Typescript Migration #13: Migrate the User Model (& API Key schema)](https://github.com/processing/p5.js-web-editor/pull/3672)
+- [pr05 Typescript Migration #14: Migrate User Controller](https://github.com/processing/p5.js-web-editor/pull/3681)
+- [pr05 Typescript Migration #15: Redux base files & migrate user preferences redux system](https://github.com/processing/p5.js-web-editor/pull/3683)
+- [pr05 Typescript Migration #16: Fix build error webpack example config](https://github.com/processing/p5.js-web-editor/pull/3696)
+- [pr05 Typescript Migration #17: Add typecheck to ci](https://github.com/processing/p5.js-web-editor/pull/3699)
+- [Pr05 Typescript Migration #18: Migrate client/modules/About & client/modules/Legal](https://github.com/processing/p5.js-web-editor/pull/3702)
+- [Pr05 Typescript Migration #19: client/common/icons](https://github.com/processing/p5.js-web-editor/pull/3703)
+- [Pr05 Typescript Migration #20: Refine server/types & client/reducer types](https://github.com/processing/p5.js-web-editor/pull/3704)
+- [Pr05 Typescript Migration #21: client/modules/User](https://github.com/processing/p5.js-web-editor/pull/3705)
+- [pr05 Typescript Migration - Followon Project: Swagger / OpenApi documentation & UI for server routes](https://github.com/processing/p5.js-web-editor/pull/3706)
+
+
+
+## Outcome:
+
+Click to view details & relevant files per outcome-item
+
+
+ All TS-related configuration for dependencies is completed
+
+- `tsconfig.json`
+- `tsconfig.base.json`
+- `.babelrc`
+- `.eslintrc`
+- `package.json > jest.config`
+- `webpack/`
+- `nodemon.json`
+- `/client/tsconfig.json`
+- `/server/tsconfig.json`
+
+
+
+ Typecheck commands have been set up & enabled on automated checks locally and on CI
+
+- `npm run typecheck` to check both the `/server` and `/client` folders
+- `npm run typecheck:server` to check only the `/server` folder
+- `npm run typecheck:client` to check only the `/client` folder
+- `package.json > husky` configured to run `npm run typecheck` during `pre-commit` check
+- `/github/workflows/test.yml` configured to run `npm run typecheck` during `test` on GHA
+
+
+
+
+ The following files have been migrated, covering at least once instance of each 'kind' of file encountered on the repo:
+
+- [x] `/common/types`
+- [.] `/client/`:
+ - [x] `/client/utils/`
+ - [x] `/client/common/`
+ - [x] `/client/components/`
+ - [x] `/client/store`
+ - [x] `/client/reducers`
+ - [x] `/client/persistState`
+ - [x] `/client/IDE/reducers/preferences`
+ - [x]`/client/IDE/actions/preferences`
+ - [x] `/client/modules/User/`
+ - [x] `/client/modules/About/`
+ - [x] `/client/modules/Legal/`
+ - [x] `/client/custom.d.ts`
+- [.] `/server`:
+ - [.] `/server/controllers`
+ - [x] `/server/controllers/user.controller/`
+ - [.] `/server/models/`
+ - [x] `/server/models/user`
+ - [x] `/server/models/apiKey`
+ - [x] `/server/routes/`
+ - [x] `/server/middleware/`
+ - [x] `/server/types/`
+ - [x] `/server/views/`
+- [.] `/server/utils/`
+ - [x] `/server/utils/generateFileSystemSafeName`
+ - [x] `/server/utils/mail`
+ - [x] `/server/utils/renderMjml`
+
+
+
+## Key Decisions:
+
+
+
+ Typescript is configured to be used for type checking only, not for transpiling
+
+
+```shell
+npm run tsc --noEmit
+```
+
+- The repo is too large to convert entirely to TS in one go, so we need to flexibly support both TS and JS files
+- We have existing legacy runtime build tools (Babel & Webpack) for the existing JS, so this was the easiest way to support both our intended direction and legacy codebase
+- Our configured automated type checking prevents PRs from being merged if they fail, so we're working towards a Typescript system without disrupting current build.
+- Once the repo has been migrated, we can update to full transpilation with `npm run tsc`
+
+
+
+
+
+
+
+ Prefer `named` exports over `default` exports where possible
+
+
+β DON'T:
+
+```ts
+// calculator.ts
+export default function multiply(a: number, b: number): numer {
+ return a * b;
+}
+
+// main.ts
+import calculate from './calculator'; // the default function is renamed and confusing for next dev to read
+
+console.log(calculate(2, 2)); // is this 2*2? 2+2? 2^2? something else?
+```
+
+β
DO:
+
+```ts
+// calculator.ts
+export function multiply(a: number, b: number): numer {
+ return a * b;
+}
+
+// main.ts
+import { multiply } from './calculator';
+
+console.log(multiply(2, 2));
+```
+
+- Default exports allow devs to rename the import anything they want, and inaccurate misnaming will cause confusion
+- Renaming default export also makes it more difficult to perform a global search on the function
+
+
+
+
+
+ Prefer `interface` over `type`
+
+
+```tsx
+// β
interface
+interface ButtonProps {
+ label: string
+ disabled?: boolean
+ onClick: () => void
+}
+const Button = ({ label, disabled, onClick }: ButtonProps) => (...)
+
+// β type
+type ButtonProps = {
+ label: string
+ disabled?: boolean
+ onClick: () => void
+}
+
+// β
keep type for primitives
+type UserId = string;
+```
+
+- Clearer semantic meaning when describing structured objects vs. primitives
+- This is not strictly enforced in linting rules, but aims to align with [Google Typescript styling](https://google.github.io/styleguide/tsguide.html#prefer-interfaces). Please see attached link for details.
+
+
+
+
+
+
+
+ If possible, add unit tests prior to the component that you are migrating prior to performing any migration
+
+
+- This protects the app from unintended regression & also helps demonstrate to reviewers that you understand the intent of a component/file you are migrating
+- Tests also help document how the component is intended to work.
+- Please see [testing](../testing.md) for more details on general guidelines, or the example code index below.
+
+
+
+
+
+ If a component does not have an existing unit test, keep refactors/logic changes outside of Typescript Migration PRs
+
+
+
+
+
+
+ Add JSDocs & specify the `Express` `RequestHandler` generics to `/server` controller methods in the following example:
+
+
+```ts
+// see server/controllers/user.controller/userPreferences.ts
+
+/**
+ * - Method: `PUT`
+ * - Endpoint: `/preferences`
+ * - Authenticated: `true`
+ * - Id: `UserController.updatePreferences`
+ *
+ * Description:
+ * - Update user preferences, such as AppTheme
+ */
+export const updatePreferences: RequestHandler<
+ {}, // request params type if there are any, extending RouteParam
+ UpdatePreferencesResponseBody, // response body type
+ UpdatePreferencesRequestBody // request body type
+ // query params type if there are any
+> = async (req, res) => {
+ // ... rest of code
+};
+```
+
+- JSDocs will reduce cognitive load for other developers and enable them to see the controllers details on hover.
+- Add the JSDocs to any `client` controllers that use these endpoints.
+
+
+
+
+
+
+
+
+
+ Best-effort & evolving-precision principle towards defining types
+
+
+- Because we are adding types into a legacy project originally written without types, there are sometimes inconsistencies between component contracts, or misalignments between type shapes or name conventions that make adding in types difficult.
+- As such make a best effort at being as precise as possible with context clues, but when in doubt, selecting a broader type (eg. `string` instead of an `enum`) is valid and we can update to be stricter as the migration continues.
+
+
+
+
+
+
+
+ `/server` types live in `/server/types`. `/client` types are co-located (currently). Shared types between the `/server` and `/client` live in `/common/types`.
+
+
+- `/server` types are in `/types` folder
+ - These types should serves the source-of-truth for the rest of the app.
+- Pull any types that are relevant to share with the `./client` into the `./common/types` folder
+- `/client` types are co-located for now
+ - Components have their own types so they will get very numerous and messy
+ - However this is open to proposals for change
+
+
+
+## Configuration Summary:
+
+
+
+ Relevant PRs
+
+
+- [pr05 Typescript #1: Set up TS dependencies in the root & client](https://github.com/processing/p5.js-web-editor/pull/3533)
+- [pr05 Typescript #2: automatically resolve imports of ts files & migrate instance of client/utils file](https://github.com/processing/p5.js-web-editor/pull/3540)
+- [pr05 Typescript Migration #10: Setup Server TS Dependencies & migrate instance of server file](https://github.com/processing/p5.js-web-editor/pull/3636)
+- [pr05 Typescript Migration #15: Redux base files & migrate user preferences redux system](https://github.com/processing/p5.js-web-editor/pull/3683)
+- [pr05 Typescript Migration #16: Fix build error webpack example config](https://github.com/processing/p5.js-web-editor/pull/3696)
+- [pr05 Typescript Migration #17: Add typecheck to ci](https://github.com/processing/p5.js-web-editor/pull/3699)
+
+
+
+## Migration Tutorial:
+
+[Video Guide - Migrating the `client/modules/User/pages/AccountView`](https://youtu.be/y84SVy7lAgg)
+
+
+
+
+ Text Guide
+
+ TO DO
+
+
+
+## Examples Index:
+
+### Client Files:
+
+
+ React component
+
+- [IconButton](https://github.com/processing/p5.js-web-editor/blob/develop/client/common/IconButton.tsx)
+- [IconButton test](https://github.com/processing/p5.js-web-editor/blob/develop/client/common/IconButton.test.tsx)
+
+
+
+
+ Normal TS file
+
+- [formatDate](https://github.com/processing/p5.js-web-editor/blob/develop/client/utils/formatDate.ts)
+- [formateDate test](https://github.com/processing/p5.js-web-editor/blob/develop/client/utils/formatDate.test.ts)
+
+
+
+
+ Hook
+
+- [usePrevious](https://github.com/processing/p5.js-web-editor/blob/develop/client/common/usePrevious.ts)
+- [usePrevious test](https://github.com/processing/p5.js-web-editor/blob/develop/client/common/usePrevious.test.ts)
+
+
+
+
+ Redux
+
+- To be updated pending open PR
+
+
+
+
+ Custom type declaration file
+
+- [custom.d.ts](https://github.com/processing/p5.js-web-editor/blob/develop/client/custom.d.ts)
+ - Use this to extend any client namespaced types (eg. Window) or file extensions (.svg, .mp3)
+
+
+
+### Server Files:
+
+
+ Types are extracted into /server/types in a barrel structure
+
+ - [types/userPreferences](https://github.com/processing/p5.js-web-editor/blob/develop/server/types/userPreferences.ts)
+ - [types/index](https://github.com/processing/p5.js-web-editor/blob/develop/server/types/index.ts)
+ - All server types are exported here
+
+
+
+
+ Routes
+
+- [routes/user.routes.ts](https://github.com/processing/p5.js-web-editor/blob/develop/server/routes/user.routes.ts)
+ - Format the routes by 'subdomain' if the file is particularly large
+ - Add the method & path in code comments for easier global search
+
+
+
+
+ Model
+
+- [models/user](https://github.com/processing/p5.js-web-editor/blob/develop/server/models/user.ts)
+- [models/user test](https://github.com/processing/p5.js-web-editor/blob/develop/server/models/__test__/user.ts)
+
+
+
+
+ Controller
+
+- [controllers/user.controller > index file](https://github.com/processing/p5.js-web-editor/blob/develop/server/controllers/user.controller/index.ts)
+ - Note that controllers should be organised in barrel format with an index file.
+- [controllers/user.controller > updateSettings method](https://github.com/processing/p5.js-web-editor/blob/develop/server/controllers/user.controller/userPreferences.ts)
+- [controllers/user.controller > updateSettings method test](https://github.com/processing/p5.js-web-editor/blob/develop/server/controllers/user.controller/__tests__/userPreferences.test.ts)
+
+
+
+
+ Custom type declaration for a namespace for a dependency
+
+ - [types/express](https://github.com/processing/p5.js-web-editor/blob/develop/server/types/express/index.d.ts)
+ - Extend the `express` namespace `Request.User` with a custom user type.
+ - [types/jest-express](https://github.com/processing/p5.js-web-editor/blob/develop/server/types/jest-express/index.d.ts)
+ - Parallel change on `jest-express` to extend `Request.User` in the test environment
+
+
+
+### Common Files:
+
+
+ Types shared across the server to client are exported in /common/types
+
+ - [types/index](https://github.com/processing/p5.js-web-editor/blob/develop/common/types/index.ts)
+ - Note that for some APIs (eg. user) we don't want to export **all** types, we want to specifically name the types to share with the client (eg. not `UserDocument`)
+
+
+
+## Next Step Issues:
+
+
+ Migrate the rest of the repo to Typescript
+
+- [Issue Link - TODO]()
+
+- Prioritise `/server` if possible
+- Testing is mandatory for `/server` migration
+- For `/client` files, if the component does not hit the `/server` api, it is ready for migration.
+- If it does it is recommended to wait for the relevant `/server` system to be migrated first (eg. Projects, Collections)
+
+
+
+
+ Add end-to-end tests to cover the core user flows
+
+- [Issue Link - TODO]()
+
+- Writing a suite of e2e tests to cover core user flows would enable security against regression with fewer test files necessary
+- This can be done with Playwrite or Cypress & can be integrated into CICD pipelines.
+- Examples of core user flows include:
+ - `User can log in`
+ - `User can save a sketch & see it in their sketches`
+- To be discussed further with the contributor community.
+
+
+
+
+ Create a OpenAPI/Swagger documentation microsite for the server APIs
+
+
+
+- [Swagger.ui](https://swagger.io/tools/swagger-ui/)
+- [Issue Link - TODO]()
+
+- This would enable new contributors to have a centralised location to look for APIs
+- Also aligns with current API documentation standards as of 2025
+- Current API documentation lives [here](https://github.com/processing/p5.js-web-editor/blob/develop/contributor_docs/public_api.md) and does not contain all the APIs
+- [Proof of concept PR here](https://github.com/processing/p5.js-web-editor/pull/3706)
+ - I have written out the User related APIs by hand, but ideally we would have automation to check that this document is accurate, or to autogenerate the document, or autogenerate types & routes from the document.
+
+
diff --git a/contributor_docs/typescript_migration.md b/contributor_docs/typescript_migration.md
index e1d481871f..44c9e0e773 100644
--- a/contributor_docs/typescript_migration.md
+++ b/contributor_docs/typescript_migration.md
@@ -1,22 +1,13 @@
# TypeScript Migration
-This repository is undergoing a TypeScript migration as part of the **2025 pr05 Grant: Incremental Typescript Migration of the p5.js Web Editor**, running **July β October 31, 2025**. Details on the [pr05 grant](https://github.com/processing/pr05-grant/wiki/2025-pr05-Program-Page) and [migration project](https://github.com/processing/pr05-grant/wiki/2025-pr05-Project-List#incremental-typescript-migration-for-the-p5js-editor).
+This repository is undergoing a Typescript migration, initiated through the **2025 pr05 Grant: Incremental Typescript Migration of the p5.js Web Editor**, running **July β October 31, 2025**.
-## Phase 1: Grant Work (July β October 31, 2025)
+For further details on the initial migration project, please see the [project appendix](./pr05_2025_typescript_migration.md)
-During this period, the grant team will:
+Below are some guidelines on completing the migration.
-- Configure and enable TypeScript across the project (`tsconfig`, linting, type checking, etc).
-- Set up linting, testing, and other related developer tooling for TS.
-- Begin migrating selected JavaScript files to TypeScript.
-- Prepare documentation and workflow so migration tasks can become **good first issues** for new contributors.
+## Migration Approach:
-> **Note:** While this initial setup and partial migration is in progress, contributions to the migration itself will **not** be open to the public.
-
-## Phase 2: Open Contribution (After October 31, 2025)
-
-When the grant period ends:
-
-- The migration effort will open up to all contributors.
-- This section will include **guidelines, tutorials, and examples** for migrating files from JavaScript to TypeScript in this project.
-- Migration tasks will be clearly labeled in the issue tracker (e.g., `good first issue`, `typescript migration`).
\ No newline at end of file
+- [TS Configuration Summary](pr05_2025_typescript_migration/index.md#configuration-summary)
+- [Migration Tutorial](pr05_2025_typescript_migration/index.md#migration-tutorial)
+- [TS & Code style decisions](pr05_2025_typescript_migration/index.md#key-decisions)
diff --git a/package.json b/package.json
index 643d468aa3..7336e68958 100644
--- a/package.json
+++ b/package.json
@@ -144,7 +144,6 @@
"@types/nodemailer": "^7.0.1",
"@types/nodemailer-mailgun-transport": "^1.4.6",
"@types/passport": "^1.0.17",
- "@types/passport": "^1.0.17",
"@types/react": "^16.14.0",
"@types/react-dom": "^16.9.25",
"@types/react-router-dom": "^5.3.3",