refactor(examples): improve examples app, reorganize examples by steveruizok · Pull Request #7957 · tldraw/tldraw

steveruizok · 2026-02-16T00:25:32Z

In order to make the examples app easier to navigate and maintain, this PR reorganizes all example directories into category-based subfolders so that the category is derived from the folder structure rather than from frontmatter metadata.

Key changes:

Move all ~150 example directories into category subfolders: collaboration, configuration, data/assets, editor-api, events, getting-started, layout, shapes/tools, ui, and use-cases
Derive the category from the folder path instead of requiring it in README frontmatter
Lazy-load README markdown content (description/details) so it's only fetched when the info dialog is opened, reducing initial bundle size
Remove the category and hide frontmatter fields from all README files
Remove unused useMergedRefs hook
Update writing-examples.md to document the new folder structure convention

Change type

improvement

Test plan

Run yarn dev and open the examples app at localhost:5420
Verify all example categories appear in the sidebar
Click through examples in each category and verify they load correctly
Open the info dialog on an example and verify the description/details load
Verify the URL paths still use the example slug (not the category prefix)

Release notes

Reorganize examples into category-based subfolders for better project structure

Note

Medium Risk
Touches example discovery/build-time transforms and routing assumptions; regressions would mainly surface as missing/incorrect examples or broken info dialogs/paths rather than core SDK behavior.

Overview
Examples are now discovered from nested src/examples/**/README.md paths, with category derived from the folder structure (including slash categories like shapes/tools) instead of README.md frontmatter; all READMEs remove category/hide fields and the build validates categories.

Example README handling is refactored in Vite to export meta plus loadComponent(), and adds loadContent() to lazy-load description/details only when the info dialog opens (UI updated accordingly). Routing/E2E utilities are updated to use slug-only URLs despite nested folders, a couple example imports are fixed for the new paths, and an unused useMergedRefs hook is removed; docs are updated to reflect the new structure.

^{Written by Cursor Bugbot for commit 36b1b3a. This will update automatically on new commits. Configure here.}

Move example directories into category-based subfolders (collaboration, configuration, data/assets, editor-api, events, getting-started, layout, shapes/tools, ui, use-cases) so category is derived from the folder structure rather than frontmatter. Lazy-load README content to reduce initial bundle size, remove unused useMergedRefs hook, and remove the category/hide frontmatter fields from all README files.

vercel · 2026-02-16T00:25:37Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
examples	Ready	Preview	Feb 16, 2026 8:28am

5 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
analytics	Ignored	Preview	Feb 16, 2026 8:28am
chat-template	Ignored	Preview	Feb 16, 2026 8:28am
tldraw-docs	Ignored	Preview	Feb 16, 2026 8:28am
tldraw-shader	Ignored	Preview	Feb 16, 2026 8:28am
workflow-template	Ignored	Preview	Feb 16, 2026 8:28am

Move the new example added on main into the category subfolder structure and remove the category frontmatter field.

cloudflare-workers-and-pages · 2026-02-16T00:28:45Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	branching-chat-template	`8a6caa1`	Commit Preview URL Branch Preview URL	Feb 16 2026, 12:42 AM

…ory folders The test was reading the top-level examples directory expecting slug names, but after reorganization it now contains category folders. Recursively walk the directory tree to find actual example slugs by looking for README.md files.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-16T00:50:52Z

apps/examples/src/index.tsx

@@ -26,7 +26,7 @@ setDefaultEditorAssetUrls(assetUrls)
 setDefaultUiAssetUrls(assetUrls)
 const gettingStartedExamples = examples.find((e) => e.id === 'Getting started')
 if (!gettingStartedExamples) throw new Error('Could not find getting started examples')
-const basicExample = gettingStartedExamples.value.find((e) => e.title === 'Tldraw component')
+const basicExample = gettingStartedExamples.value[0]


Fragile array indexing replaces explicit example lookup

Medium Severity

The code changed from explicitly finding the example by title (find((e) => e.title === 'Tldraw component')) to implicitly taking the first sorted element (value[0]). This is fragile and will break if any getting-started example is added with lower priority or with priority 0 and an alphabetically earlier title. The explicit search was more robust and maintainable.

…erties table Updated the release notes guide to fix table formatting for PR categorization and improved the layout of the example properties section in the writing examples documentation. Ensured consistent alignment and clarity in both documents.

Updated the ExampleMetaModule definition in examples.tsx to use an interface instead of a type, enhancing type extensibility and clarity in the codebase.

followup to #7957 was causing docs builds to fail: ``` Error: ENOENT: no such file or directory, open '/Users/mime/Sites/tldraw/apps/examples/src/examples/collaboration/README.md' at Object.openSync (node:fs:559:18) at Object.readFileSync (node:fs:443:35) at generateSection ``` ### Change type - [ ] `bugfix` - [ ] `improvement` - [ ] `feature` - [ ] `api` - [x] `other`  --- > [!NOTE] > **Low Risk** > Limited to docs content generation logic; main risk is misclassification or missing example articles if the expected folder structure differs. > > **Overview** > Fixes docs build failures when generating the `examples` section by changing article discovery to **recursively locate `README.md` files** instead of assuming a flat directory layout. > > This refactors `generateSection` to use explicit article source lists (`getRegularArticleSources` vs `getExampleArticleSources`), derives example `articleId`/`categoryId` from folder paths, and allows `getArticleData` to accept a category override so example category assignment no longer depends on frontmatter. > > Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 8dd4f97. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).

@steveruizok

Closes #8099 PR #7957 reorganized examples from flat `apps/examples/src/examples/{name}` into category subdirectories (`shapes/tools/`, `data/assets/`, `events/`, `ui/`, etc.). All ~115 "Related examples" GitHub links across 40 docs files now 404. This PR updates every link to use the new paths. Also fixes 2 misnamed example references in `default-shapes.mdx`: - `custom-styles` → `shapes/tools/shape-with-custom-styles` - `shape-options` → `configuration/configure-shape-util` @steveruizok we sometimes point to hosted examples and sometimes to code on github, not sure if intentional or not? ### Change type - [x] `bugfix` ### Test plan 1. Open any docs page with "Related examples" links (e.g. `/sdk-features/shapes`, `/sdk-features/tools`, `/sdk-features/deep-links`) 2. Click the GitHub example links 3. Verify they resolve to the correct example directory on GitHub ### Release notes - Fix ~115 broken GitHub example links across SDK documentation  --- > [!NOTE] > **Low Risk** > Low risk: documentation-only changes that update URLs and a couple of example name corrections, with no runtime or API impact. > > **Overview** > Fixes SDK docs and release notes that linked to example directories that were moved in the examples reorg. > > Updates "Related examples" links across many `sdk-features/*.mdx` pages to point at the new categorized paths (e.g. `ui/`, `events/`, `configuration/`, `editor-api/`, `shapes/tools/`, `data/assets/`, `use-cases/`, `layout/`). Also corrects a couple of misnamed example references in `default-shapes.mdx` and updates the v4.3.0 release note link for the pin bindings example. > > Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit de7a306. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).

@steveruizok

Closes #8099 PR #7957 reorganized examples from flat `apps/examples/src/examples/{name}` into category subdirectories (`shapes/tools/`, `data/assets/`, `events/`, `ui/`, etc.). All ~115 "Related examples" GitHub links across 40 docs files now 404. This PR updates every link to use the new paths. Also fixes 2 misnamed example references in `default-shapes.mdx`: - `custom-styles` → `shapes/tools/shape-with-custom-styles` - `shape-options` → `configuration/configure-shape-util` @steveruizok we sometimes point to hosted examples and sometimes to code on github, not sure if intentional or not? ### Change type - [x] `bugfix` ### Test plan 1. Open any docs page with "Related examples" links (e.g. `/sdk-features/shapes`, `/sdk-features/tools`, `/sdk-features/deep-links`) 2. Click the GitHub example links 3. Verify they resolve to the correct example directory on GitHub ### Release notes - Fix ~115 broken GitHub example links across SDK documentation  --- > [!NOTE] > **Low Risk** > Low risk: documentation-only changes that update URLs and a couple of example name corrections, with no runtime or API impact. > > **Overview** > Fixes SDK docs and release notes that linked to example directories that were moved in the examples reorg. > > Updates "Related examples" links across many `sdk-features/*.mdx` pages to point at the new categorized paths (e.g. `ui/`, `events/`, `configuration/`, `editor-api/`, `shapes/tools/`, `data/assets/`, `use-cases/`, `layout/`). Also corrects a couple of misnamed example references in `default-shapes.mdx` and updates the v4.3.0 release note link for the pin bindings example. > > Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit de7a306. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).

huppy-bot bot added the improvement Product improvement label Feb 16, 2026

steveruizok added the maybe An idea, something to try and see label Feb 16, 2026

steveruizok added 2 commits February 16, 2026 00:26

Merge remote-tracking branch 'origin/main' into examples-reorg-cleanup

51e05a2

refactor(examples): move text-mass-style-updates into ui/ subfolder

8a6caa1

Move the new example added on main into the category subfolder structure and remove the category frontmatter field.

vercel bot temporarily deployed to Preview – workflow-template February 16, 2026 00:42 Inactive

vercel bot temporarily deployed to Preview – tldraw-shader February 16, 2026 00:42 Inactive

vercel bot temporarily deployed to Preview – chat-template February 16, 2026 00:42 Inactive

cursor bot reviewed Feb 16, 2026

View reviewed changes

steveruizok marked this pull request as draft February 16, 2026 08:20

steveruizok added 2 commits February 16, 2026 08:21

refactor(examples): change ExampleMetaModule from type to interface

890ee34

Updated the ExampleMetaModule definition in examples.tsx to use an interface instead of a type, enhancing type extensibility and clarity in the codebase.

steveruizok changed the title ~~refactor(examples): reorganize examples into category subfolders~~ refactor(examples): improve examples app, reorganize examples Feb 16, 2026

steveruizok temporarily deployed to e2e-dotcom February 16, 2026 08:25 — with GitHub Actions Inactive

steveruizok temporarily deployed to bemo-canary February 16, 2026 08:25 — with GitHub Actions Inactive

github-actions bot deployed to bemo-preview February 16, 2026 08:26 View deployment

vercel bot deployed to Preview – examples February 16, 2026 08:28 View deployment

steveruizok marked this pull request as ready for review February 16, 2026 09:26

steveruizok removed the maybe An idea, something to try and see label Feb 16, 2026

steveruizok added this pull request to the merge queue Feb 16, 2026

Merged via the queue into main with commit a1e3b71 Feb 16, 2026
16 checks passed

steveruizok deleted the examples-reorg-cleanup branch February 16, 2026 13:54

mimecuvalo mentioned this pull request Feb 18, 2026

docs: fix up examples #8009

Merged

5 tasks

max-drake mentioned this pull request Feb 20, 2026

Camera options example view source link 404s #8046

Open

This was referenced Feb 26, 2026

Example links in docs are broken after examples reorganization #8099

Closed

docs: fix broken example links after examples reorganization #8102

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(examples): improve examples app, reorganize examples#7957

refactor(examples): improve examples app, reorganize examples#7957
steveruizok merged 6 commits intomainfrom
examples-reorg-cleanup

steveruizok commented Feb 16, 2026 •

edited by cursor bot

Loading

Uh oh!

vercel bot commented Feb 16, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Feb 16, 2026 •

edited

Loading

Uh oh!

cursor bot left a comment

Uh oh!

cursor bot Feb 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

steveruizok commented Feb 16, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change type

Test plan

Release notes

Uh oh!

vercel bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-workers-and-pages bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 16, 2026

Choose a reason for hiding this comment

Fragile array indexing replaces explicit example lookup

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

steveruizok commented Feb 16, 2026 •

edited by cursor bot

Loading

vercel bot commented Feb 16, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Feb 16, 2026 •

edited

Loading