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.

Documented generating filter types for each app in a project

Damian Legawiec286284ee03ba
diff --git a/docs/developer/cli/quickstart.mdx b/docs/developer/cli/quickstart.mdx
index 8c32cd3f1e..e091c9485a 100644
--- a/docs/developer/cli/quickstart.mdx
+++ b/docs/developer/cli/quickstart.mdx
@@ -253,14 +253,16 @@ spree generate migration AddPositionToSpreeBrands position:integer # Rails buil
### `spree filters types`
-Generate TypeScript declarations for your app's list filters, so the SDKs accept and autocomplete the filters and sort fields your app adds. It reads them from the running app; run it again after you change a filter.
+Generate TypeScript declarations for your app's list filters, so the SDKs accept and autocomplete the filters and sort fields your app adds. It reads them from the running app and writes one file per run, so run it once for each app that uses an SDK, and again after you change a filter.
```bash
-spree filters types --api store --out src/types/spree-filters.d.ts # storefront, @spree/sdk
-spree filters types --api admin --out src/types/spree-filters.d.ts # dashboard, @spree/admin-sdk
-spree filters types --from filter-tables.json --api seller # from `bin/rails spree:api:filter_tables` output
+spree filters types --api store --out apps/storefront/src/types/spree-filters.d.ts # @spree/sdk
+spree filters types --api admin --out apps/dashboard/src/types/spree-filters.d.ts # @spree/admin-sdk
+spree filters types --api seller --out apps/seller-dashboard/src/types/spree-filters.d.ts # @spree/seller-sdk
```
+`--from <file>` reads the tables from `bin/rails spree:api:filter_tables` output instead of the running app.
+
See [using your own filters from TypeScript](/developer/core-concepts/search-filtering#using-your-own-filters-from-typescript).
### `spree migrate`
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdx
index 58da7b83bc..23c3591f0a 100644
--- a/docs/developer/core-concepts/search-filtering.mdx
+++ b/docs/developer/core-concepts/search-filtering.mdx
@@ -288,23 +288,35 @@ Every entry is a filter any caller of that API can run. Keep back-office fields
The SDKs type each `list()` call with the filters Spree itself declares. A filter your app adds works in the API at once, but TypeScript rejects it until it is declared, because the published types cannot know about it. There are three ways to use it.
-**Generate the declarations (recommended).** This reads your app's filters, the ones Spree declares and the ones you added, and writes a declaration file for the SDK you use. Run it again after you add or change a filter:
+**Generate the declarations (recommended).** This reads your app's filters, the ones Spree declares and the ones you added, and writes a declaration file for one SDK. Each frontend uses its own SDK, so generate a file for each app in your project, from the project root:
+
+| App | SDK | `--api` |
+|---|---|---|
+| `apps/storefront` | `@spree/sdk` | `store` |
+| `apps/dashboard` | `@spree/admin-sdk` | `admin` |
+| `apps/seller-dashboard` (marketplaces) | `@spree/seller-sdk` | `seller` |
<Tabs>
<Tab title="Spree CLI">
```bash
- spree filters types --api store --out src/types/spree-filters.d.ts
+ spree filters types --api store --out apps/storefront/src/types/spree-filters.d.ts
+ spree filters types --api admin --out apps/dashboard/src/types/spree-filters.d.ts
+ spree filters types --api seller --out apps/seller-dashboard/src/types/spree-filters.d.ts
```
</Tab>
<Tab title="Without CLI">
```bash
- bin/rails spree:api:filter_tables > filter-tables.json
- npx @spree/cli filters types --from filter-tables.json --api store --out src/types/spree-filters.d.ts
+ cd server
+ bin/rails spree:api:filter_tables > ../filter-tables.json
+ cd ..
+ npx @spree/cli filters types --from filter-tables.json --api store --out apps/storefront/src/types/spree-filters.d.ts
+ npx @spree/cli filters types --from filter-tables.json --api admin --out apps/dashboard/src/types/spree-filters.d.ts
+ npx @spree/cli filters types --from filter-tables.json --api seller --out apps/seller-dashboard/src/types/spree-filters.d.ts
```
</Tab>
</Tabs>
-Use `--api store` for storefront code (`@spree/sdk`), `--api admin` for the dashboard and Admin API integrations (`@spree/admin-sdk`), and `--api seller` for the seller panel (`@spree/seller-sdk`). After that, every `list()` call accepts and autocompletes your filters and sort fields, and a misspelled one is still a compile error.
+Run them again after you add or change a filter, and commit the generated files with the app code that uses them. Match `--api` to the app: a storefront file generated with `--api admin` compiles, but declares the Admin API's filters. After that, every `list()` call accepts and autocompletes your filters and sort fields, and a misspelled one is still a compile error.
**Send it unchecked.** Filters inside `q` are sent as given, without type checking or autocomplete:
diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdx
index b4740521ea..87c5edd1da 100644
--- a/docs/developer/upgrades/5.6-to-6.0.mdx
+++ b/docs/developer/upgrades/5.6-to-6.0.mdx
@@ -1035,10 +1035,10 @@ Each `list()` method now takes the filters and sort fields its endpoint accepts.
- **Filters your backend adds are compile errors until you declare them.** The published types list only the filters Spree itself declares. Any filter or scope your backend adds (through `Spree.ransack.add_attribute`, `add_scope` or a model decorator) still works in the API, but TypeScript rejects the key. Generate the declarations from your app, and run the command again whenever a filter changes:
```bash
- spree filters types --api store --out src/types/spree-filters.d.ts
+ spree filters types --api store --out apps/storefront/src/types/spree-filters.d.ts
```
- For a one-off filter, send it inside `q` instead (`list({ q: { erp_id_eq: 'ERP-1' } })`), which is not type checked. See [using your own filters from TypeScript](/developer/core-concepts/search-filtering#using-your-own-filters-from-typescript) for both, and for declaring filters by hand.
+ Generate one for the dashboard (`--api admin --out apps/dashboard/src/types/spree-filters.d.ts`) and the seller panel (`--api seller`) too, if they use your filters. For a one-off filter, send it inside `q` instead (`list({ q: { erp_id_eq: 'ERP-1' } })`), which is not type checked. See [using your own filters from TypeScript](/developer/core-concepts/search-filtering#using-your-own-filters-from-typescript) for both, and for declaring filters by hand.
- **Amount filters take decimal strings.** `price_gte`, `price_lte` and the other money filters are typed as strings, like every money value in 6.0. Send `'20.00'`, not `20`.