Fix/10up block theme readme by pdavies88 · Pull Request #321 · 10up/wp-scaffold

pdavies88 · 2026-03-25T05:01:29Z

Description of the Change

For the 10up-block-theme it performs the following:

Adds in READMEs for context on the theme
Update dependencies to latest versions
Converts JS to TS
Provides Example Custom Block
Fixes naming mismatching in Theme

Closes: N/A

How to test the Change

Can be pulled into a local WP build and run and function as normal

Changelog Entry

Added - README for 10up-Block-Theme and a Example Custom Block
Changed - JS file to TS, theme naming mismatching, and updated dependencies in the theme
Removed - styles folder as it could cause confusion between assets folder

Credits

Props @pdavies88

Checklist:

I agree to follow this project's Code of Conduct.
I have updated the documentation accordingly.
I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
All new and existing tests pass.

pdavies88 · 2026-03-25T05:04:23Z

@fabiankaegy will add some time on our calendar to chat further. But at least wanted to get a draft started of a robust README on the Theme itself as team members may use it on a one off and want to know how it works. Also saw we hadn't updated the dependencies for awhile and the project was still using JS. Anywho feel free to add comments and guidance but wanted to get the wheels turning to get your thoughts.

fabiankaegy

Thanks so much for getting this started @pdavies88 🚀

Left a bunch of notes inline and also pinned @darylldoyle & @claytoncollie for additional thoughts :)

fabiankaegy · 2026-03-25T06:46:52Z

Big fan of making this change official in the theme here 👍

Something I always needed to do in projects though is add the following to the .eslintrc file:

{ "parser": "@typescript-eslint/parser", "extends": ["@10up/eslint-config/wordpress"], "plugins": ["@typescript-eslint"], "rules": {} }

fabiankaegy · 2026-03-25T06:49:27Z

Do you really think there is value in having the example block back in here?

Part of the reason why I removed it was that I ended up seeing it nor removed on client projects. And since we have the scaffold:block command in the theme here I always found it nicer / easier to just have that present.

fabiankaegy · 2026-03-25T06:51:04Z

I'd actually be in favor or removing this because it's also something we always have to remove and folks forget that :/

fabiankaegy · 2026-03-25T06:55:33Z

I know it goes against what I was saying above, but I would like to keep these here.

Section styles is an under utilized feature in my opinion so I want users of this theme to wonder about it and start to learn more about them.

See https://ignitewp.10uplabs.com/block-styling-and-css/#section-styles-in-ignite

fabiankaegy · 2026-03-25T07:10:01Z

+- `register_theme_blocks()` scans `dist/blocks/*/block.json` and calls `register_block_type_from_metadata()` for each found block.
+- `allowed_block_types_all` filter extends allowed blocks with theme blocks.
+- `enqueue_theme_block_styles()` scans `dist/blocks/autoenqueue/**/*.css` and registers/enqueues style/script for each block with assets info from `GetAssetInfo`.
+- includes block render filter for TenUp navigation block (removes ARIA roles for fallback markup compatibility).


Not sure I understand what's meant by this

fabiankaegy · 2026-03-25T07:10:19Z

+- `enqueue_theme_block_styles()` scans `dist/blocks/autoenqueue/**/*.css` and registers/enqueues style/script for each block with assets info from `GetAssetInfo`.
+- includes block render filter for TenUp navigation block (removes ARIA roles for fallback markup compatibility).
+
+### 6.2 Blocks directory structure


Let's mention the scaffold command here

fabiankaegy · 2026-03-25T07:11:29Z

+
+### 7.2 Theme script inclusion
+
+- `src/ThemeCore::theme_setup()` calls `add_theme_support('editor-styles')` and `add_editor_style('/dist/css/frontend.css')`.


This is only for editor stuff. From the heading I would have expected something about the Asset trait from the framework and how to enqueue things

fabiankaegy · 2026-03-25T07:12:59Z

+
+## 16. Further notes
+
+- This theme is designed around a 10up block theme pattern (colors, spacing, utilities, templates).


Not sure I understand what is meant by this

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

…ck-theme-readme

claytoncollie · 2026-04-10T06:14:51Z

@pdavies88 I don't agree with having smaller readme's throughout the codebase that can easily become out of date. I think this either should be a CLAUDE.md file (still run into same out of date issue) or place all of this into the root README/CLAUDE.md files.

claytoncollie · 2026-04-10T06:16:11Z

@pdavies88 I agree with @fabiankaegy that we should not provide an example block here as people do not take ownership and make sure it gets deleted. We have so many resources to scaffold this ou either with a cli or the documentation at gutenberg.10up.com

claytoncollie · 2026-04-10T06:16:52Z

@pdavies88 same thing here. Either a CLAUDE.md file or we consilidate into the main readme

claytoncollie · 2026-04-10T06:18:27Z

 			"blocksDir": "./blocks"
 		}
+	},
+	"optionalDependencies": {


@fabiankaegy Does 10up toolkit already load these?

claytoncollie · 2026-04-10T06:19:53Z

+
+## 2. Requirements
+
+- PHP >= 8.2


@fabiankaegy we should bump this to 8.4 IMO cc @pdavies88

claytoncollie · 2026-04-10T06:20:09Z

+## 2. Requirements
+
+- PHP >= 8.2
+- Node >= 18


@fabiankaegy we should bump this to v24 IMO cc @pdavies88

claytoncollie · 2026-04-10T06:20:27Z

+
+- PHP >= 8.2
+- Node >= 18
+- Composer


@pdavies88 if we are putting versions, this should be Composer 2

claytoncollie · 2026-04-10T06:21:25Z

+npm run build
+```
+
+### 4.2 Local development


@pdavies88 this totally ignore PHP commands in composer.json. we should treat both PHP and JS/CSS as equal partners

claytoncollie · 2026-04-10T06:21:48Z

+### 4.2 Local development
+
+- `npm run watch` (or `npm start`) → 10up-toolkit watch with HMR/hot-refresh
+- `composer exec phpcs -- --standard=WordPress` → PHP lint


@pdavies88 should be composer run lint

claytoncollie · 2026-04-10T06:23:19Z

+### 4.3 Common gotchas
+
+- Always build `dist/` after changing source assets (`assets/`, `blocks/`, `src/`).
+- If using a check-in strategy for `dist/`, ensure CI runs `npm run build` before release.


@pdavies88 this is very nuanced and vague. I think we remove. this assumes too much about deployment which can be varied

claytoncollie · 2026-04-10T06:23:44Z

+- Always build `dist/` after changing source assets (`assets/`, `blocks/`, `src/`).
+- If using a check-in strategy for `dist/`, ensure CI runs `npm run build` before release.
+- `theme.json` is the source of truth for editor styles, palette, and layout. Adjust there for global styles.
+- Some references may still use legacy naming in older helper docs; prefer 10up-block-theme naming in code changes.


@pdavies88 can we remove this? I though we caught all of the instances.

claytoncollie · 2026-04-10T06:24:29Z

+### 4.1 Quick start (repeat for copy/paste)
+
+```bash
+cd /path/to/themes/10up-block-theme


@pdavies88 you should not have to do this operation. Both NPM and Composer work from the wp-content directory to install and build all assets, not just the theme

claytoncollie · 2026-04-10T06:25:39Z

+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url> 10up-block-theme


@pdavies88 I think we are getting too specific here for a theme only setup, and not sticking to the original intent of the repo which covers a large majority of use cases. Most projects use this entire scaffold, not just the theme cc @fabiankaegy

claytoncollie · 2026-04-10T06:28:01Z

@pdavies88 sorry, i am just not seeing this is the theme readme. I think this is going to throw people off the main path. I appreciate that some projects only use the theme, but a vast majority will use the entire scaffold. Fabian has spent a lot of time making things run from the wp-content directory link install and built and scaffold commands and now we are bypassing all of that work. I think it is fine to explain this theme, but then say to reference the main readme for scaffold and install instructions. cc @fabiankaegy

claytoncollie · 2026-04-10T06:30:11Z

+
+---
+
+## 5. Core bootstrapping path


@pdavies88 Similar to what we are finding with AGENTS.md and CLAUDE.md file, this information can go stale over time. I think all of this function reference should be removed from here in favor of docblocks on the class or methods it relates to.

claytoncollie · 2026-04-10T06:31:31Z

+
+---
+
+## 16. Further notes


@pdavies88 I think we can remove this section. feels redundant after all that is said eariler

claytoncollie · 2026-04-10T06:32:35Z

+
+---
+
+## 15. Helpful commands summary


@pdavies88 I think we can remove this section. This is the third instance where we are listing the same commands.

claytoncollie · 2026-04-10T06:32:47Z

+
+---
+
+## 14. Key entrypoints quick map


@pdavies88 do we need an entry point for CSS?

claytoncollie · 2026-04-10T06:33:12Z

+
+---
+
+## 13. Maintenance tasks


@pdavies88 can we consolidate these commands into the earlier list at the start of this file?

Co-authored-by: Clayton Collie <clayton.collie@gmail.com>

…fold into fix/10up-block-theme-readme

pdavies88 · 2026-04-15T01:16:43Z

@claytoncollie @fabiankaegy this PR has been heavily overhauled via our chat today.
Right now the PR does the following:

Converts JS files over to TS - This also applies to the block generator
Adds in TS support into the 10up-block-theme. Additional dev dependencies help resolve any TS warnings that may occur
README inside of the 10up-block-theme has been updated but kept trim to help folks focus on the basics
Used https://www.npmjs.com/package/@ravi.nder/wp-gutenberg-compat to add in the ability to check @wordpress/* projects for when they are added to be in line with the WordPress version.
Reran npm i which is where the bulk of the line changes seems to come from but it looks like we need to commit the package-lock for our GHAs to actually work properly

pdavies88 · 2026-04-16T17:58:34Z

@fabiankaegy @claytoncollie adjustments have been made to also align 10up-theme as well to use TS as the default. In that theme I aligned it with the 10up-block-theme for the theme.json, adding of custom blocks, and example pattern. I also added a clean command in the root of the repo to clear out stale package-lock and node_modules.

pdavies88 added 2 commits March 24, 2026 16:37

fix: init README baseline for theme

b8cce98

feat: add example block, updated README, and newest NPM packages

ca12766

pdavies88 self-assigned this Mar 25, 2026

pdavies88 requested a review from fabiankaegy March 25, 2026 05:01

fabiankaegy requested review from claytoncollie and darylldoyle March 25, 2026 06:45

fabiankaegy requested changes Mar 25, 2026

View reviewed changes

pdavies88 and others added 6 commits April 9, 2026 20:44

Update themes/10up-block-theme/blocks/example-block/index.ts

9d5f38c

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/templates/README.md

ede7918

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/templates/README.md

88fda3d

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/parts/README.md

81f246c

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Update themes/10up-block-theme/README.md

965f336

Co-authored-by: Fabian Kägy <mail@fabian-kaegy.de>

Merge branch 'trunk' of github.com:10up/wp-scaffold into fix/10up-blo…

ffed049

…ck-theme-readme

claytoncollie reviewed Apr 10, 2026

View reviewed changes

Comment thread themes/10up-block-theme/README.md Outdated

claytoncollie reviewed Apr 10, 2026

View reviewed changes

pdavies88 and others added 10 commits April 14, 2026 11:47

fix: remove nested readmes

56aa066

fix: update create block template for scaffold

45a9e76

fix: stop tracking root package lock

c456533

Apply suggestion from @claytoncollie

bcb85bc

Co-authored-by: Clayton Collie <clayton.collie@gmail.com>

fix: readd package-lock for build process

45f3b78

Merge branch 'fix/10up-block-theme-readme' of github.com:10up/wp-scaf…

50c0be1

…fold into fix/10up-block-theme-readme

fix: streamline readme

60ef4c1

fix: update readme for both root scaffold and solo theme

f783ea4

fix: remove optionalDependcies and add back styles

fe64bef

fix: update README numbering and fix ts warning

7cb4126

pdavies88 marked this pull request as ready for review April 15, 2026 01:08

pdavies88 requested review from claytoncollie and fabiankaegy April 15, 2026 01:09

pdavies88 added 3 commits April 16, 2026 13:42

fix: baseline alignment of 10up-theme

bb6bdd4

fix: typescript typing baselines

a51516e

fix: commit root updates

b0112ab


		### 7.2 Theme script inclusion

		- `src/ThemeCore::theme_setup()` calls `add_theme_support('editor-styles')` and `add_editor_style('/dist/css/frontend.css')`.


		## 16. Further notes

		- This theme is designed around a 10up block theme pattern (colors, spacing, utilities, templates).

Conversation

pdavies88 commented Mar 25, 2026

Description of the Change

How to test the Change

Changelog Entry

Credits

Checklist:

Uh oh!

pdavies88 commented Mar 25, 2026

Uh oh!

fabiankaegy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pdavies88 commented Apr 15, 2026

Uh oh!

pdavies88 commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development