Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Address PR review: release ordering, turbo edge, CodeQL hardening

Damian Legawiec659a75a5d36b
diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml
index 574321256d..99b9509ac8 100644
--- a/.github/workflows/packages.yml
+++ b/.github/workflows/packages.yml
@@ -289,7 +289,11 @@ jobs:
release-cli:
name: "CLI - Release"
- needs: check
+ # Gated on release-dashboard: the CLI tarball embeds the dashboard-starter
+ # template with ^x.y.z pins for @spree/dashboard{,-ui,-core} — publishing
+ # it before those versions exist on npm would ship a scaffold whose
+ # install fails until the dashboard release lands.
+ needs: [check, release-dashboard]
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
diff --git a/docs/api-reference/admin-api/endpoints.mdx b/docs/api-reference/admin-api/endpoints.mdx
index 39734d1947..b7b365a8b7 100644
--- a/docs/api-reference/admin-api/endpoints.mdx
+++ b/docs/api-reference/admin-api/endpoints.mdx
@@ -366,7 +366,7 @@ Endpoints marked — are exempt from scope checks (authentication and session en
| Method | Path | Required scope | Summary |
|---|---|---|---|
-| `POST` | `/translations/batch` | *write_<resource> for every resource type in the batch (for API-key authentication)* | Batch upsert translations |
+| `POST` | `/translations/batch` | `write_*` (eg. `write_products`) for every resource type in the batch (for API-key authentication) | Batch upsert translations |
## Webhook endpoints
diff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdx
index 5a9c2d7139..8a0fd40625 100644
--- a/docs/developer/dashboard/overview.mdx
+++ b/docs/developer/dashboard/overview.mdx
@@ -1,23 +1,43 @@
---
title: React Dashboard Overview
sidebarTitle: Overview
-description: How the React Dashboard is structured, how to customize existing screens and how to build new features
+description: Learn about the Spree React Dashboard architecture and how to customize it and extend it
---
<Info>
-The React Dashboard is a Developer Preview — APIs may still change between releases. In Spree 6 it becomes the default admin interface.
+The React Dashboard is currently a **Developer Preview** — APIs may still change between releases.
+In Spree 6 it will become the default Admin interface replacing the Spree 5 admin.
</Info>
-The React Dashboard is a single-page application (SPA) that talks to the Spree Admin API and is built on three packages:
+The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](/api-reference/admin-api). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:
+
+| Layer | Choice |
+|---|---|
+| Build & dev | [Vite](https://vitejs.dev/) |
+| Routing | [TanStack Router](https://tanstack.com/router) (file-based, type-safe) |
+| Data fetching | [TanStack Query](https://tanstack.com/query) |
+| Forms | [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) |
+| UI primitives | [shadcn/ui](https://ui.shadcn.com/) + [Base UI](https://base-ui.com/) + [Tailwind CSS](https://tailwindcss.com/) |
+| Icons | [lucide-react](https://lucide.dev/) |
+| Charts | [Recharts](https://recharts.org/) |
+| Rich text | [Tiptap](https://tiptap.dev/) |
+| Notifications | [Sonner](https://sonner.emilkowal.ski/) |
+| Lint & format | [Biome](https://biomejs.dev/) |
+
+### Packages
+
+Dashboard consinsts of 3 NPM packages, each with a different purpose. You can import any of them in your host app or plugin package.
| Package | What it contains | When you touch it |
|---|---|---|
-| `@spree/dashboard-ui` | Design system: shadcn primitives + headless composed components (`PageHeader`, `ResourceLayout`, `ResourceTable`'s rendering layer, etc.) + design tokens | Building custom UI — primitives + compounds you can drop anywhere |
+| `@spree/dashboard-ui` | Design system: [shadcn](https://ui.shadcn.com/) primitives + headless composed components (`PageHeader`, `ResourceLayout`, `ResourceTable`'s rendering layer, etc.) + design tokens | Building custom UI — primitives + compounds you can drop anywhere |
| `@spree/dashboard-core` | Framework: registries (nav, route, slot, table, settings-nav), providers (auth, permission, store), admin SDK client, infra hooks, the `defineDashboardPlugin` API | Extending the admin — every customization API lives here |
| `@spree/dashboard` | The deployable SPA: routes, resource hooks, schemas, locale strings, app shell | Replacing or restyling specific routes (rare) |
Most customization happens via `@spree/dashboard-core`. You import its registries from your own host-app code (or from a separate plugin package) to add nav entries, routes, slot widgets, table columns, and translations.
+You can also built your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.
+
## Get the dashboard
Your copy of the dashboard is a small Vite app (the "host app") that imports `<Dashboard />` from `@spree/dashboard` — you own its `package.json`, Vite config, and a `src/plugins.ts` for customizations. Two ways to get one:
@@ -31,7 +51,7 @@ Either way: `cd apps/dashboard && npm run dev`, open http://localhost:5173, and
There are two ways to customize the dashboard. **Both use the same APIs** — the only difference is packaging.
-### 1. Customize in your host app
+### 1. Customize in your host app (Recommended)
You're building a Spree store and want a "Featured products" page or a custom card on every product detail. Edit your dashboard app directly — it ships a `src/plugins.ts` file for exactly this (in a `create-spree-app` project the dashboard app lives at `apps/dashboard/`):
diff --git a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
index 758399f90e..5510c2e6c5 100644
--- a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
+++ b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
@@ -21,8 +21,7 @@ Graduate to a real database column only when the attribute needs **list operatio
| You need… | Custom field | Real column |
|---|---|---|
| Editing on the product form | ✅ zero code | ✅ this recipe |
-| Filtering / sorting the products list | ❌ | ✅ via Ransack |
-| A database index, Rails validations, queries in Ruby | ❌ | ✅ |
+| Filtering / sorting the products list in Admin | ❌ | ✅ via Ransack |
| Merchants defining the field themselves at runtime | ✅ | ❌ |
Lead time is a column because its whole point is the query: *"show me everything that ships slow, slowest first."*
@@ -45,30 +44,36 @@ end
**The serializer** — makes the attribute *readable* (hydrates the form, renders the table cell):
```ruby
-# app/serializers/my_plugin/product_serializer.rb
-module MyPlugin
+# app/serializers/admin/product_serializer.rb
+module Admin
class ProductSerializer < Spree::Api::V3::Admin::ProductSerializer
- typelize lead_time_days: 'number | null'
attributes :lead_time_days
end
end
# config/initializers/spree.rb
-Spree.api.admin_product_serializer = 'MyPlugin::ProductSerializer'
+Spree.api.admin_product_serializer = 'Admin::ProductSerializer'
```
**The permitted param** — makes it *writable* (the form's Save ships it in the same PATCH as core fields). The read and write names must match:
```ruby
-# app/controllers/my_plugin/products_controller_decorator.rb
-module MyPlugin
- module ProductsControllerDecorator
- def permitted_params
- super.merge(params.permit(:lead_time_days))
+# app/controllers/spree/api/v3/admin/products_controller_decorator.rb
+module Spree
+ module Api
+ module V3
+ module Admin
+ module ProductsControllerDecorator
+ def permitted_params
+ super.merge(params.permit(:lead_time_days))
+ end
+ end
+
+ ProductsController.prepend(ProductsControllerDecorator)
+ end
end
end
end
-Spree::Api::V3::Admin::ProductsController.prepend(MyPlugin::ProductsControllerDecorator)
```
**The Ransack allowlist** — makes it *filterable and sortable*. Both the list's sort param and every filter predicate go through Ransack, and Ransack refuses attributes that aren't allowlisted:
diff --git a/docs/docs.json b/docs/docs.json
index a849cc0dc6..42b16ac236 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -281,7 +281,7 @@
{
"item": "Extending",
"icon": "puzzle",
- "description": "Customize admin, models, and business logic",
+ "description": "Customize admin panel, API, and business logic",
"groups": [
{
"group": "Tutorial",
@@ -298,8 +298,8 @@
]
},
{
- "group": "Classic Admin",
- "icon": "ruby",
+ "group": "Admin Panel",
+ "icon": "gauge",
"pages": [
"developer/admin/admin",
"developer/admin/extending-ui",
@@ -392,6 +392,7 @@
"item": "Dashboard",
"icon": "gauge",
"description": "React dashboard",
+ "hidden": true,
"groups": [
{
"group": "Overview",
diff --git a/packages/dashboard-plugin-example/package.json b/packages/dashboard-plugin-example/package.json
index 3b908d6d49..7837f7b0d5 100644
--- a/packages/dashboard-plugin-example/package.json
+++ b/packages/dashboard-plugin-example/package.json
@@ -40,6 +40,9 @@
"react-i18next": "^17.0.8"
},
"devDependencies": {
+ "@spree/admin-sdk": "workspace:^",
+ "@spree/dashboard-core": "workspace:^",
+ "@spree/dashboard-ui": "workspace:^",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
"typescript": "~6.0.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0528e03153..a79aee2898 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -401,15 +401,6 @@ importers:
packages/dashboard-plugin-example:
dependencies:
- '@spree/admin-sdk':
- specifier: workspace:^
- version: link:../admin-sdk
- '@spree/dashboard-core':
- specifier: workspace:^
- version: link:../dashboard-core
- '@spree/dashboard-ui':
- specifier: workspace:^
- version: link:../dashboard-ui
'@tanstack/react-query':
specifier: ^5.100.9
version: 5.100.9([email protected])
@@ -432,6 +423,15 @@ importers:
specifier: ^17.0.8
devDependencies:
+ '@spree/admin-sdk':
+ specifier: workspace:^
+ version: link:../admin-sdk
+ '@spree/dashboard-core':
+ specifier: workspace:^
+ version: link:../dashboard-core
+ '@spree/dashboard-ui':
+ specifier: workspace:^
+ version: link:../dashboard-ui
'@types/react':
specifier: ^19.2.14
version: 19.2.14
diff --git a/spree/dashboard/app/controllers/spree/dashboard/app_controller.rb b/spree/dashboard/app/controllers/spree/dashboard/app_controller.rb
index f3f7de5068..59dd0e5858 100644
--- a/spree/dashboard/app/controllers/spree/dashboard/app_controller.rb
+++ b/spree/dashboard/app/controllers/spree/dashboard/app_controller.rb
@@ -11,7 +11,16 @@ module Spree
# falls back to index.html with no-cache so deploys take effect on the
# next navigation. No authentication — the bundle is public client code;
# the SPA authenticates its API calls itself.
- class AppController < ActionController::API
+ class AppController < ActionController::Base
+ # GET-only file serving mutates nothing, but enable forgery protection
+ # anyway so the controller stays safe if an action is ever added.
+ protect_from_forgery with: :exception
+ # `verify_same_origin_request` blocks JavaScript responses to plain GET
+ # requests — protection against JSONP-style data leaks from dynamically
+ # generated JS. The Vite bundle is static public code that the SPA's own
+ # <script> tags must load, which is exactly that request shape.
+ skip_after_action :verify_same_origin_request
+
def show
root = dist_root
return head :not_found unless root
@@ -37,13 +46,21 @@ module Spree
root if root.directory?
end
- # Resolve a request path to a real file inside the dist directory,
- # rejecting anything that escapes it (`..`, absolute paths, symlinks
- # pointing outside are covered by the expanded-path prefix check).
+ # Resolve a request path to a real file inside the dist directory.
+ # Defense in depth against traversal: reject null bytes, absolute
+ # paths, and any `.`/`..` segment before touching the filesystem, then
+ # verify the expanded path still lives under the dist root (which also
+ # covers symlinks pointing outside it).
def resolve_file(root, relative_path)
- return if relative_path.blank?
+ return if relative_path.blank? || relative_path.include?("\0")
+
+ relative = Pathname.new(relative_path)
+ return if relative.absolute?
+
+ segments = relative.each_filename.to_a
+ return if segments.empty? || segments.any? { |segment| segment == '.' || segment == '..' }
- candidate = root.join(relative_path).expand_path
+ candidate = root.join(*segments).expand_path
return unless candidate.to_s.start_with?("#{root}#{File::SEPARATOR}")
candidate if candidate.file?