Skip to content

Commit 1fa1a60

Browse files
sdimunziosdimunzio
committed
Please provide the file changes (diffs) so I can generate a commit message.
1 parent c0f4968 commit 1fa1a60

1 file changed

Lines changed: 244 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 244 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,245 @@
11
# data-viz-wordpress
2-
Data Viz Wordpress
2+
3+
A **pnpm monorepo** that packages all WordPress plugins, themes, shared npm libraries, and CLI tools required to run a **Data Visualization dashboard** on WordPress. It is maintained by Development Gateway and produces both published npm packages and a Docker image for self-hosted deployments.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
- [Overview](#overview)
10+
- [Repository Structure](#repository-structure)
11+
- [Packages](#packages)
12+
- [Plugins](#plugins)
13+
- [Theme](#theme)
14+
- [Docker Image](#docker-image)
15+
- [Getting Started](#getting-started)
16+
- [Scripts](#scripts)
17+
- [Release Management](#release-management)
18+
- [CI/CD](#cicd)
19+
- [License](#license)
20+
21+
---
22+
23+
## Overview
24+
25+
This repository brings together everything needed to extend a WordPress site into a full-featured data visualization platform:
26+
27+
| Layer | What lives here |
28+
|---|---|
29+
| **React / Gutenberg blocks** | Custom blocks that embed charts, maps, and filters directly in the WordPress editor |
30+
| **REST API extensions** | Custom endpoints that feed data to those blocks |
31+
| **Multilingual support** | Full i18n layer via a bundled WP Multilang plugin |
32+
| **Shared npm packages** | Reusable React components and utility types published to npm under `@devgateway/` |
33+
| **Scaffolding CLIs** | `create-wp-customizer` and `upgrade-wp-customizer` for bootstrapping new customizer projects |
34+
| **Custom WordPress theme** | `dg-semantic` — a block-compatible theme pre-wired for data viz pages |
35+
| **Docker image** | A ready-to-run `wordpress:fpm-alpine`-based image with all plugins and the theme pre-installed |
36+
37+
---
38+
39+
## Repository Structure
40+
41+
```
42+
data-viz-wordpress/
43+
├── packages/ # Published npm packages
44+
│ ├── commons/ # @devgateway/dvz-wp-commons
45+
│ ├── create-wp-customizer/ # @devgateway/create-wp-customizer CLI
46+
│ └── upgrade-wp-customizer/ # @devgateway/upgrade-wp-customizer CLI
47+
├── plugins/ # WordPress plugins (pnpm workspace members)
48+
│ ├── wp-react-blocks-plugin/ # Gutenberg blocks for data visualization
49+
│ ├── wp-react-custom-api/ # Custom REST API endpoints
50+
│ ├── wp-react-custom-multilang/ # Multilingual plugin (WP Multilang fork)
51+
│ └── wp-react-custom-rest-menu/ # Menu REST API endpoints
52+
├── wp-content/ # Third-party plugins and language files
53+
├── wp-theme/ # dg-semantic WordPress theme
54+
├── custom/ # PHP runtime config (upload limits, etc.)
55+
├── Dockerfile # Multi-stage production image
56+
├── wordpress.sh # Container entrypoint script
57+
├── pnpm-workspace.yaml
58+
└── package.json
59+
```
60+
61+
---
62+
63+
## Packages
64+
65+
All packages are versioned and released with [Changesets](https://github.com/changesets/changesets) and published to npm under the `@devgateway` scope.
66+
67+
### `@devgateway/dvz-wp-commons`
68+
69+
> `packages/commons`
70+
71+
Shared React components and utilities used across the Gutenberg blocks. Includes:
72+
73+
- **API & data configuration** — `APIConfig`, `CSVSourceConfig`, `DataFilters`
74+
- **Chart primitives** — `ChartColors`, `ChartLegends`, `ChartMeasures`, `Tooltip`, `Format`
75+
- **Block editor helpers** — `BlockEditWithAPIMetadata`, `BlockEditWithFilters`, `ComponentWithSettings`
76+
77+
Built with TypeScript; exports both JS and `.d.ts` type definitions.
78+
79+
### `@devgateway/create-wp-customizer`
80+
81+
> `packages/create-wp-customizer`
82+
83+
CLI (`create-wp-customizer`) that scaffolds a new WordPress customizer project from an interactive prompt. Uses `@clack/prompts` for the UX and `cross-spawn` to bootstrap the project.
84+
85+
### `@devgateway/upgrade-wp-customizer`
86+
87+
> `packages/upgrade-wp-customizer`
88+
89+
CLI that upgrades an existing customizer project to the latest conventions. Parses and transforms existing source files using `@babel/parser`.
90+
91+
---
92+
93+
## Plugins
94+
95+
### `wp-react-blocks-plugin`
96+
97+
The core plugin. Contains all custom [Gutenberg blocks](https://developer.wordpress.org/block-editor/) built with React and [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/). Each block is a self-contained React component that fetches data from the REST API and renders charts, maps, or filter controls.
98+
99+
**Environment variables consumed at build time:**
100+
101+
| Variable | Default | Description |
102+
|---|---|---|
103+
| `BLOCKS_CATEGORY` | `wp-react-lib-blocks` | Block category slug in the editor |
104+
| `BLOCKS_NS` | `viz` | Namespace prefix for block names |
105+
106+
### `wp-react-custom-api`
107+
108+
Extends the WordPress REST API with custom endpoints required by the data viz blocks. Register your data sources here.
109+
110+
### `wp-react-custom-multilang`
111+
112+
A bundled fork of [WP Multilang](https://wordpress.org/plugins/wp-multilang/) with configuration for the data viz content types. Provides per-language versions of posts, terms, meta, menus, and widgets — without creating duplicate database rows.
113+
114+
> **Note:** This plugin is excluded from the pnpm workspace because it has no npm build step.
115+
116+
### `wp-react-custom-rest-menu`
117+
118+
Adds REST endpoints for WordPress nav menus:
119+
120+
| Endpoint | Description |
121+
|---|---|
122+
| `GET /menus/v1/menus` | List all registered menus |
123+
| `GET /menus/v1/menus/{slug}` | Get a single menu by slug or ID |
124+
| `GET /menus/v1/locations` | List all menu locations |
125+
| `GET /menus/v1/locations/{slug}` | Get the menu assigned to a location |
126+
127+
Compatible with ACF menu attributes and the Menu Image plugin.
128+
129+
---
130+
131+
## Theme
132+
133+
### `dg-semantic`
134+
135+
> `wp-theme/` → deployed to `wp-content/themes/dg-semantic/`
136+
137+
A custom block-compatible WordPress theme built for data visualization pages. Key features:
138+
139+
- `theme.json` v2 — spacing, font sizes, and layout tokens
140+
- WP Multilang integration (`wpm-config.json`)
141+
- Custom post type and taxonomy registration
142+
- ACF field registration (`_custom_fields.php`)
143+
- Custom admin styles and MIME type support (SVG, etc.)
144+
145+
---
146+
147+
## Docker Image
148+
149+
The repository ships a multi-stage `Dockerfile` that produces a minimal, production-ready image.
150+
151+
| Stage | Base image | What it does |
152+
|---|---|---|
153+
| `base` | `node:22-slim` | Sets up pnpm / corepack |
154+
| `installer` | — | `pnpm install --frozen-lockfile` |
155+
| `builder` | — | Builds all npm packages and plugins; assembles `wp-content/` |
156+
| `runtime` | `wordpress:6.8.2-fpm-alpine` | Copies PHP config, `wp-content.tgz`, and entrypoint |
157+
158+
The final image exposes ports **80** and **443** and runs via `php-fpm`.
159+
160+
### Entrypoint: `wordpress.sh`
161+
162+
On startup the script:
163+
164+
1. Extracts `/tmp/wp-content.tgz` into the WordPress root (skipped when `SKIP_WP_UPDATE=1`).
165+
2. Delegates to the official WordPress Docker entrypoint.
166+
3. Sets write permissions on `wp-content/uploads/`.
167+
168+
**Development tip:** Set `SKIP_WP_UPDATE=1` to mount your local `wp-content/` without it being overwritten on every restart.
169+
170+
---
171+
172+
## Getting Started
173+
174+
### Prerequisites
175+
176+
- [Node.js 22+](https://nodejs.org/)
177+
- [pnpm 10+](https://pnpm.io/) (`corepack enable && corepack prepare pnpm@latest --activate`)
178+
- [Docker](https://www.docker.com/) (for the full WordPress stack)
179+
180+
### Install dependencies
181+
182+
```bash
183+
pnpm install
184+
```
185+
186+
### Build all packages and plugins
187+
188+
```bash
189+
pnpm build
190+
```
191+
192+
### Build only the npm packages
193+
194+
```bash
195+
pnpm build:npm-packages
196+
```
197+
198+
### Run with Docker
199+
200+
```bash
201+
docker build -t data-viz-wordpress .
202+
```
203+
204+
---
205+
206+
## Scripts
207+
208+
| Script | Description |
209+
|---|---|
210+
| `pnpm build` | Build every workspace member recursively |
211+
| `pnpm build:npm-packages` | Build only the published npm packages |
212+
| `pnpm version` | Bump versions from pending changesets (`changeset version`) |
213+
| `pnpm release` | Publish packages to npm (`changeset publish`) |
214+
215+
---
216+
217+
## Release Management
218+
219+
Versioning is handled by [Changesets](https://github.com/changesets/changesets).
220+
221+
1. After making changes, run `pnpm changeset` and follow the prompts to describe what changed.
222+
2. When ready to release, run `pnpm version` to apply version bumps and update changelogs.
223+
3. Run `pnpm release` (or let CI do it) to publish to npm.
224+
225+
Changelogs are generated in GitHub format and linked to the `devgateway/data-viz-wordpress` repository.
226+
227+
---
228+
229+
## CI/CD
230+
231+
Three GitHub Actions workflows live in `.github/workflows/`:
232+
233+
| Workflow | Trigger | What it does |
234+
|---|---|---|
235+
| `build-and-release-wordpress.yml` | Manual dispatch | Builds the Docker image and pushes it to the registry with a semantic version tag |
236+
| `build-and-pre-release-wordpress.yml` | Manual dispatch | Same, but for pre-release tags |
237+
| `release-npm-packages.yml` | Push to `main` (packages/\* or .changeset/\* changed) or manual dispatch | Publishes updated npm packages via Changesets |
238+
239+
Dependabot is configured to open weekly PRs for npm dependency updates (max 1 open at a time).
240+
241+
---
242+
243+
## License
244+
245+
GPL-2.0-or-later — see [LICENSE](./LICENSE).

0 commit comments

Comments
 (0)