wpapp
/wpapp
Build WordPress web applications using the WpApp framework. Use when: (1) Creating new WpApp plugins or routes (2) Working with BaseApp/BaseStorage patterns (3) Configuring masterbar, access control, or routing (4) Adding database tables with schema management (5) User asks about WpApp features or configuration
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.
LGPL, otwarta.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Build WordPress web applications using the WpApp framework. Use when: (1) Creating new WpApp plugins or routes (2) Working with BaseApp/BaseStorage patterns (3) Configuring masterbar, access control, or routing (4) Adding database tables with schema management (5) User asks about WpApp features or configuration
Original author description
Build WordPress web applications using the WpApp framework. Use when: (1) Creating new WpApp plugins or routes (2) Working with BaseApp/BaseStorage patterns (3) Configuring masterbar, access control, or routing (4) Adding database tables with schema management (5) User asks about WpApp features or configuration
How it works
- Creating a New Project
- Generated Project Structure
- Generated App Lifecycle
- Quick Patterns
- Storage Choices
- Template Structure
- Configuration Options
- Menu Methods
- Abilities
- Verification
SKILL.md preview
---
name: wpapp
description: |
Build WordPress web applications using the WpApp framework. Use when:
(1) Creating new WpApp plugins or routes
(2) Working with BaseApp/BaseStorage patterns
(3) Configuring masterbar, access control, or routing
(4) Adding database tables with schema management
(5) User asks about WpApp features or configuration
---
# WpApp Development
WpApp builds web applications on WordPress with routing, theme isolation, admin bar integration, and admin color scheme tokens.
## Creating a New Project
Scaffold a new WpApp plugin:
```bash
composer create-project akirk/create-wp-app my-app
```
This prompts for plugin name, namespace, author, URL path, and setup type. The default setup type is Full, which creates a `BaseApp` scaffold. Choose Minimal only for a small direct `WpApp` setup.
## Generated Project Structure
Full setup creates:
```text
my-app/
├── my-app.php # Main plugin file
├── src/
│ └── App.php # BaseApp subclass with lifecycle hooks
├── templates/
│ └── index.php # Main route template
├── composer.json
└── .gitignore
```
Minimal setup creates:
```text
my-app/
├── my-app.php # Main plugin file with WpApp initialization
├── templates/
│ └── index.php
├── composer.json
└── .gitignore
```
## Generated App Lifecycle
- Read the generated files before modifying them.
- Keep `__construct()` focused on creating/configuring `WpApp`, assigning storage objects, and attaching WordPress hooks.
- Do not call `register_post_type()`, `register_taxonomy()`, `flush_rewrite_rules()`, `wp_add_dashboard_widget()`, REST route registration, or other WordPress-hooked feature registration directly from `__construct()`.
- Register custom post types and taxonomies on the WordPress `init` hook.
- When a custom post type or taxonomy uses `show_in_rest => true` (the block editor needs it), wire its `rest_controller_class` to `\WpApp\Rest\Access::protect_post_type()` / `::protect_taxonomy()` — that gates its REST reads to the app's capability. Otherwise published entries are readable anonymously over `/wp/v2/<type>` regardless of `public => false`. See docs/access-control.md. (Requires `akirk/wp-app ^1.5`.)
- Register dashboard widgets on the WordPress `wp_dashboard_setup` hook.
- Define WpApp routes in `setup_routes()` and WpApp menu/masterbar entries in `setup_menu()`.
- Run activation-only work, including custom table creation and rewrite flushing, from the plugin activation hook.
## Quick Patterns
### Minimal Setup
```php
$app = new WpApp( __DIR__ . '/templates', 'my-app' );
$app->init();
```
### BaseApp Setup
```php
use WpApp\BaseApp;
use WpApp\WpApp;
class App extends BaseApp {
public function __construct() {
$this->app = new WpApp( $this->get_template_dir(), $this->get_url_path(), [
'require_login' => true,
'app_name' => 'My App',
] );
add_action( 'init', [ $this, 'register_post_types' ] );
}
protected function get_url_path(): string {
return 'my-app';
}
protected function get_template_dir(): string {
return dirname( __DIR__ ) . '/templates';
}
protected function setup_database(): void {}
protected function setup_routes(): void {
$this->app->route( 'dashboard' );
$this->app->route( 'user/{user_id}' );
}
protected function setup_menu(): void {
$this->app->add_menu_item( 'dashboard', 'Dashboard', home_url( '/my-app/dashboard' ) );
}
}
```
### REST-Gated Custom Post Type
A `show_in_rest` post type is readable anonymously over `/wp/v2/<type>` unless its
REST reads are gated (front-end `require_login` does not cover REST). Set each
type's `rest_controller_class` to `Access::protect_*`, which records the capability
and returns the gated controller class:
```php
use WpApp\Rest\Access;
public function register_post_types(): void {
register_post_type( 'note', [
'public' => false,
'show_in_rest' => true,
'rest_controller_class' => Access::protect_post_type( 'note', 'read' ),
'supports' => [ 'title', 'editor', 'author', 'custom-fields' ],
] );
register_taxonomy( 'note_tag', 'note', [
'public' => false,
'show_in_rest' => true,
'rest_controller_class' => Access::protect_taxonomy( 'note_tag', 'read' ),
] );
}
```
### Route with Parameters
```php
$app->route( 'user/{user_id}' ); // templates/user.php
$app->route( 'posts/{id}/edit' ); // templates/posts-edit.php
```
Access in template: `$user_id = get_query_var( 'user_id' );`
### Per-Route Access Control
```php
$app->route( 'admin', 'admin.php', [], 'manage_options' );
```
## Storage Choices
- Prefer WordPress-native storage before custom tables:
- Custom post types and post meta for content-like records.
- Taxonomies, terms, and term meta for shared categories, labels, and groupings.
- User meta for per-user settings, preferences, and profile data.
- Use custom tables and `BaseStorage` only when native WordPress storage does not fit, such as high-volume rows, relational data, or records that do not map cleanly to posts, terms, or users.
- If using `BaseStorage`, instantiate the storage class during app construction and call `create_tables()` during plugin activation.
### BaseStorage Schema
```php
class Storage extends BaseStorage {
// Keyed by unprefixed table name; create_tables() adds the prefix and
// wraps each definition in CREATE TABLE with the site's charset.
protected function get_schema() {
return [
'myapp_items' => "id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
user_id bigint(20) unsigned NOT NULL,
data longtext,
PRIMARY KEY (id),
KEY user_id (user_id)",
];
}
}
```
## Template Structure
Keep CSS and JavaScript in asset files loaded through the scoped enqueue helpers. Do not write inline `<style>` or `<script>` blocks, `style` attributes, or event-handler attributes in app templates. Pass dynamic values through HTML data attributes for an external script to read.
```php
<!DOCTYPE html>
<html <?php wp_app_language_attributes(); ?>>
<head>
<title><?php wp_app_the_title( 'Page' ); ?></title>
<?php wp_app_head(); ?>
</head>
<body>
<?php wp_app_body_open(); ?>
<!-- content -->
<?php wp_app_body_close(); ?>
</body>
</html>
```
## Configuration Options
| Option | Default | Description |
|--------|---------|-------------|
| `app_name` | Auto-generated from URL path | Display name for your app in the admin bar |
| `require_login` | `true` | Require authentication (set `false` for a public app) |
| `require_capability` | `null` | Required WordPress capability (overrides `require_login`; implies login) |
| `show_masterbar_for_anonymous` | `true` | Show nav for logged-out users |
| `show_wp_logo` | `true` | Show WordPress logo |
| `show_site_name` | `true` | Show site name |
| `admin_bar_app_link` | `true` | Add app entry to admin bar |
| `clear_admin_bar` | `false` | Remove all WP admin bar items |
| `launcher` | `true` | Register with My Apps / OpenStation (`false`, `true`, or a launcher name; `my_apps` is the old name) |
| `app_icon` | `null` | URL to an app icon or Dashicon class (`my_apps_icon` is the old name) |
| `app_icon_background` | `null` | Tile colour or gradient behind a Dashicon/letter icon, e.g. `linear-gradient(135deg, #1e3c72, #2a5298)` |
| `app_icon_color` | `null` | Glyph colour for a Dashicon/letter icon, e.g. `#fff` |
| `app_icon_shadow` | `null` | `true` for a soft glyph shadow, or a CSS `text-shadow` value |
Plain Dashicons on the default white tile look generic; always pair a Dashicon with `app_icon_background` and `app_icon_color`.
Use admin color variables in app CSS instead of hard-coding WordPress admin colors:
```css
.button-primary {
background: var(--wp-app-color-primary);
color: var(--wp-app-color-on-primary);
}
.button-primary:hover {
background: var(--wp-app-color-primary-hover);
}
```
Pair background and text tokens so light/dark mode can switch both sides together:
- `--wp-app-color-background` with `--wp-app-color-text`
- `--wp-app-color-surface` with `--wp-app-color-text`
- `--wp-app-color-surface-alt` with `--wp-app-color-muted` or `--wp-app-color-text`
- `--wp-app-color-primary` with `--wp-app-color-on-primary`
- `--wp-app-color-secondary` with `--wp-app-color-secondary-text`
Avoid mixing tokenized colors with hard-coded colors such as `#fff`, `#222`, or `white`, because the hard-coded side will not adapt when the app switches between light and dark mode.
## Menu Methods
```php
$app->add_menu_item( 'id', 'Label', $url ); // Submenu under app
$app->add_top_level_menu_item( 'id', 'Label', $url ); // Top-level
$app->add_user_menu_item( 'id', 'Label', $url ); // User dropdown
```
## Abilities
Expose the app's data through the WordPress Abilities API so assistants, automation and other apps can use it without reading the code. Register categories on `wp_abilities_api_categories_init` and abilities on `wp_abilities_api_init`, guarded by `function_exists( 'wp_register_ability' )`. Use the app's route slug as namespace and category (`community/list-posts`) and reuse `$app->get_required_capability()` in `permission_callback`. Leave `meta.public` unset: the permission callback is the gate, and AI Assistant / MCP Connect expose the ability to signed-in users who pass it.
Design rules — the description and schemas are the whole API for the caller:
- One ability per verb-noun (`list-posts`, `get-post`, `create-post`); never an `action` switch or a run-anything escape hatch.
- The description says what is returned and what to do on failure, not just what happens.
- Every property has a description; inputs set `additionalProperties: false`; closed sets use `enum`; always give `output_schema`.
- IDs say which ability produced them and which accept them ("as returned by community/list-posts").
- Annotate accurately: `readonly`, `destructive`, `idempotent`.
- Failures are `WP_Error` with stable codes (`not_found`), never `false`/`null`/`[]`.
- `list-*` pages (`page`, `per_page` with a maximum) and returns summaries; `get-*` returns the full record.
Full guidance and a worked example: `docs/abilities.md` and the [`community-app`](https://github.com/akirk/wp-app-examples/tree/main/community-app) example.
## Verification
- After modifying PHP, run or request a syntax check before navigating the app.
- If a WordPress runtime is available, activate the plugin and load the configured app URL after the syntax check passes.
## Detailed Documentation
For comprehensive guides, see the `docs/` directory:
- `docs/getting-started.md` - Installation and quick start
- `docs/configuration.md` - All configuration options
- `docs/routing.md` - URL patterns and parameters
- `docs/masterbar.md` - Admin bar customization
- `docs/access-control.md` - Capabilities and roles
- `docs/baseapp.md` - BaseApp and BaseStorage patterns
- `docs/abilities.md` - Exposing the app through the Abilities API and designing good abilities
Versions
The database has no other skills named wpapp.
Database snapshot: 13.11.2026 · package version 02560191a4c8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100lark-base
飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式(BaseApp/AppMode 页面与组件)、Workspace 目录、workflow、角色权限、模板中心(多维表格模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;文件导入/导出转 lark-drive,认证/授权转 lark-shared。 - 100react-router-framework-mode
Build full-stack React applications using React Router's framework mode. Use when configuring routes, working with loaders and actions, handling forms, handling navigation, pending/optimistic UI, error boundaries, or working with react-router.config.ts or other react router conventions. - 100uw-analyze-database
Use when analyzing the database layer including schema, migrations, ORM configuration, and data access patterns - 100wordpress
Expert WordPress assistance covering themes, plugins, REST API, Gutenberg blocks, and WP_Query. Use when developing custom WordPress plugins, themes, or headless CMS backends. - 100lark-base
【何时用:仅当用户明确指向飞书/Lark(发到飞书、飞书文档等)时使用;泛指做个文档或PPT或表格或方案默认走本地工具,不要误用飞书】飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、BaseApp 应用模式(页面与组件)、Workspace 目录、workflow、角色权限、模板中心(模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;导入转 lark-drive,认证转 lark-shared。 - 100web-artifacts-builder
Suite of tools for creating elaborate, multi-component web applications using modern frontend technologies (React, Tailwind CSS, shadcn/ui). Use for complex projects requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX pages.