Support File-Based Admin Page & Route Registration
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 25/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Da chiarire
- Stato di attività
- Ferma
- Stack tecnologico
- javascript, php, react, typescript
- Ambito
- backend, build-system, developer-experience, frontend
Direzione di ricerca
Inizia esaminando la documentazione di @wordpress/build a cui si fa riferimento e ispezionando la configurazione di build e gli entry point attuali di 10up-toolkit. L’issue non indica file o test esistenti; definisci la configurazione supportata di route e pagine, l’approccio del router, gli output PHP e JavaScript generati, il comportamento della migrazione e i test necessari prima che l’implementazione possa essere considerata completa.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
[!WARNING]
This feature is still experimental in core. So this is more of a placeholder for future versions of toolkit to support this once it is more ironed out in core.
Summary
WordPress core's @wordpress/build package introduces a powerful file-based routing system for admin pages. This system allows developers to create admin pages and routes through conventional directory structures, with automatic PHP registration and JavaScript bootstrapping handled by the build tool.
10up-toolkit should explore adopting this pattern to simplify admin page development in WordPress plugins.
How It Works in @wordpress/build
1. Declaring Pages in package.json
Admin pages are declared in the root package.json via wpPlugin.pages:
{
"wpPlugin": {
"pages": [
"my-settings",
{
"id": "my-dashboard",
"init": ["@my-plugin/dashboard-init"]
}
]
}
}
Page configuration options:
| Format | Example | Description |
|---|---|---|
| String | "my-settings" |
Simple page with no init modules |
| Object | { "id": "my-dashboard", "init": [...] } |
Page with initialization modules |
2. File-Based Routes
Routes are organized in a routes/ directory at the repository root:
routes/
├── home/
│ ├── package.json # Route configuration
│ ├── stage.tsx # Main content component (required)
│ ├── inspector.tsx # Sidebar component (optional)
│ ├── canvas.tsx # Custom canvas component (optional)
│ └── route.tsx # Lifecycle hooks (optional)
├── settings/
│ ├── package.json
│ └── stage.tsx
└── settings/general/
├── package.json
└── stage.tsx
3. Route Configuration
Each route's package.json defines its path and associated page:
{
"route": {
"path": "/",
"page": "my-settings"
}
}
For routes that appear on multiple pages:
{
"route": {
"path": "/settings",
"page": ["my-settings", "my-dashboard"]
}
}
4. Route Components
| File | Purpose | Required |
|---|---|---|
stage.tsx |
Main content area | Yes |
inspector.tsx |
Sidebar/inspector panel | No |
canvas.tsx |
Custom full-screen canvas (like the block editor) | No |
route.tsx |
Lifecycle hooks for data loading, auth, etc. | No |
Example stage.tsx
export default function SettingsStage() {
return (
<div>
<h1>Settings</h1>
<p>Configure your plugin settings here.</p>
</div>
);
}
Example inspector.tsx
export default function SettingsInspector() {
return (
<div>
<h2>Help</h2>
<p>Need assistance? Check the documentation.</p>
</div>
);
}
5. Route Lifecycle Hooks
The route.tsx file exports lifecycle hooks:
export const route = {
// Pre-navigation validation, auth checks
beforeLoad: async ({ params, search }) => {
const hasPermission = await checkUserPermission();
if (!hasPermission) {
throw redirect('/unauthorized');
}
},
// Data preloading
loader: async ({ params, search }) => {
const settings = await fetchSettings();
return { settings };
},
// Canvas control (for editor-like experiences)
canvas: ({ params, search }) => {
// Return CanvasData to render WordPress editor canvas
// return { postType: 'post', postId: params.id };
// Return null to use custom canvas.tsx
// return null;
// Return undefined for no canvas
return undefined;
}
};
6. Init Modules
Init modules execute during page initialization, before routes are registered. They're useful for:
- Adding icons to menu items (icons can't be passed from PHP)
- Registering command palette entries
- Setting up global state
// packages/my-dashboard-init/src/index.ts
import { dispatch } from '@wordpress/data';
import { bootStore } from '@wordpress/boot';
import { home, settings } from '@wordpress/icons';
export function init() {
dispatch(bootStore).updateMenuItem('home', { icon: home });
dispatch(bootStore).updateMenuItem('settings', { icon: settings });
}
7. Build Output
The build system generates:
build/
├── pages/
│ └── my-settings/
│ ├── page.php # Full-page mode (custom sidebar)
│ └── page-wp-admin.php # WP-Admin mode (standard interface)
├── routes/
│ ├── home/
│ │ ├── content.js # Bundled stage/inspector/canvas
│ │ └── route.js # Bundled lifecycle hooks
│ ├── settings/
│ │ └── content.js
│ └── index.php # Route registry
├── pages.php # Page registration
└── index.php # Main loader
8. Two Rendering Modes
Full-page mode (page.php):
- Takes over the entire admin screen
- Custom sidebar with route navigation
- Clean, modern interface
WP-Admin mode (page-wp-admin.php):
- Integrates within standard WordPress admin
- Keeps WordPress admin menu/header
- Routes via
pquery parameter:admin.php?page=my-settings-wp-admin&p=/settings/general
9. PHP Registration
Include the generated PHP in your plugin:
<?php
/**
* Plugin Name: My Plugin
*/
require_once plugin_dir_path( __FILE__ ) . 'build/index.php';
// Register menu items
add_action( 'admin_menu', function() {
add_menu_page(
'My Settings',
'My Settings',
'manage_options',
'my-settings', // Matches wpPlugin.pages ID
'my_settings_render_page', // Generated function
'dashicons-admin-generic',
30
);
});
🔮 Proposal for 10up-toolkit
1. File-Based Route Discovery
Support a conventional routes/ directory structure:
src/
├── routes/
│ ├── dashboard/
│ │ ├── route.json # Route configuration
│ │ ├── Stage.tsx # Main content
│ │ └── Inspector.tsx # Optional sidebar
│ └── settings/
│ ├── route.json
│ └── Stage.tsx
└── admin-pages.json # Page definitions
2. Configuration
Define pages in a dedicated config file or 10up-toolkit.config.js:
// 10up-toolkit.config.js
module.exports = {
adminPages: {
enabled: true,
pages: [
{
id: 'my-plugin-settings',
menuTitle: 'My Plugin',
capability: 'manage_options',
icon: 'dashicons-admin-generic',
position: 30
}
],
// Output directory for generated PHP
output: 'build/admin'
}
};
3. Generated PHP Registration
Generate PHP that handles:
- Menu registration via
add_menu_page()/add_submenu_page() - Script/style enqueueing
- Route data passing to JavaScript
- Capability checks
<?php
// build/admin/pages.php (generated)
function tenup_my_plugin_settings_register_page() {
add_menu_page(
__( 'My Plugin', 'my-plugin' ),
__( 'My Plugin', 'my-plugin' ),
'manage_options',
'my-plugin-settings',
'tenup_my_plugin_settings_render',
'dashicons-admin-generic',
30
);
}
add_action( 'admin_menu', 'tenup_my_plugin_settings_register_page' );
function tenup_my_plugin_settings_render() {
wp_enqueue_script( 'my-plugin-settings-page' );
wp_enqueue_style( 'my-plugin-settings-page' );
echo '<div id="my-plugin-settings-root"></div>';
}
4. JavaScript Bootstrap
Generate a bootstrap script that:
- Mounts the React app
- Sets up routing (React Router, TanStack Router, etc.)
- Loads route components dynamically
// build/admin/bootstrap.tsx (generated)
import { createRoot } from 'react-dom/client';
import { RouterProvider } from '@tanstack/react-router';
import { router } from './router';
const container = document.getElementById('my-plugin-settings-root');
if (container) {
const root = createRoot(container);
root.render(<RouterProvider router={router} />);
}
Benefits
- Convention over configuration: Drop files in the right place, they become routes
- Reduced boilerplate: No manual menu registration, script enqueueing, or render functions
- Modern DX: File-based routing familiar to Next.js/Remix developers
- Type safety: Full TypeScript support for route params and loader data
- Code splitting: Routes can be lazy-loaded for better performance
- Alignment with core: Follows patterns WordPress core is adopting
Implementation Considerations
Router Choice
Should 10up-toolkit:
- Bundle a specific router (TanStack Router, React Router)?
- Generate router-agnostic code?
- Let projects choose their router?
PHP Generation Complexity
The PHP generation needs to handle:
- Translatable strings
- Different menu types (top-level, submenu, options page)
- Capability checks
- Multisite considerations
Backward Compatibility
Projects with existing admin pages should be able to:
- Migrate incrementally
- Mix traditional and file-based pages
- Opt out entirely
Questions to Consider
- Should this be a separate package or built into 10up-toolkit core?
- What router library should be used (or should it be configurable)?
- How do we handle the inspector/canvas patterns - are they useful outside of Gutenberg-like experiences?
- Should we support the init modules pattern, or is that overkill for most plugins?
- How do we handle data loading - built-in loader pattern or let projects use React Query/SWR?
References
- @wordpress/wp-build Documentation
- @wordpress/build Package
- TanStack Router - Modern file-based routing for React
- React Router File Conventions
- Lingua principale
- JavaScript
- Stelle
- 147
- Fork
- 21
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di 10up/10up-toolkit
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
10up/10up-toolkit#486 · 1 commento · 1 reazione ·
-
Toolkit Future PlanningForse di nuovo libera @fabiankaegy l’ha presa 190 giorni fa e non c’è nessuna pull request aperta. Aperta[Type] Tracking Issue
10up/10up-toolkit#489 · 7 commenti · 2 reazioni · 1 assegnatario ·
-
CSS
Difficoltà 3/5 1-2 giorni Idoneità per principianti 58/100
10up/10up-toolkit#487 · 3 commenti ·
-
Difficoltà 3/5 1-2 giorni Idoneità per principianti 45/100
10up/10up-toolkit#482 ·
-
`10up-toolkit test-unit-jest` command does not work out of the boxForse già presa Una pull request collegata a questa issue è aperta o già unita. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 45/100
10up/10up-toolkit#480 ·
Tutte le issue di 10up/10up-toolkit
Issue simili
-
type: bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
I maintainer di solito rispondono entro 2 giorni
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 66/100
I maintainer di solito rispondono entro 1 giorno
-
ai-amazon-bedrock: a tool result that isn't a JSON object fails the next requestForse già presa @effect-bot l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 79/100
I maintainer di solito rispondono entro 1 giorno
-
[bug] Toolchain versions from `.prototools` are not inherited when moon runs from a subdirectoryAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 1 giorno
-
Edit: Tele1 Logo [SV]Apertacheck:passed logos:edit
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 72/100
I maintainer di solito rispondono entro 1 giorno