@lowdefy/codemods 6.0.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/registry.json +33 -1
- package/v6-0-0/01-migrate-plugin-packages.md +1 -1
- package/v6-0-0/03-request-timeout.md +96 -0
- package/v6-0-0/04-report-type-overrides.md +110 -0
- package/v7-0-0/01-react-icons-to-lucide.md +327 -0
- package/v7-0-0/02-clickable-html-data-events.md +102 -0
- package/v7-0-0/03-nested-event-bubbling.md +190 -0
- package/v7-0-0/react-icons-to-lucide.json +3040 -0
package/package.json
CHANGED
package/registry.json
CHANGED
|
@@ -1,9 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"versions": [
|
|
3
|
+
{
|
|
4
|
+
"version": "7.0.0",
|
|
5
|
+
"from": ">=6.0.0 <7.0.0",
|
|
6
|
+
"description": "Lucide icons replace react-icons; ClickableHtml lists its data events; nested events no longer bubble",
|
|
7
|
+
"codemods": [
|
|
8
|
+
{
|
|
9
|
+
"id": "react-icons-to-lucide",
|
|
10
|
+
"description": "Rewrite react-icons and stale Ant Design icon names to semantic or Lucide names using the v7-0-0/react-icons-to-lucide.json table, and report glyph judgement calls, unmapped names and runtime-only icon sources (the @lowdefy/icons-react-icons compatibility set covers stored names and brand icons).",
|
|
11
|
+
"path": "v7-0-0/01-react-icons-to-lucide.md"
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
"id": "clickable-html-data-events",
|
|
15
|
+
"description": "List the events each ClickableHtml block's HTML fires in its new dataEvents property (from data-event attributes and the block's events), mark data-changing events that use data-confirm as confirm: true, and report HTML built from data that inserts values unescaped.",
|
|
16
|
+
"path": "v7-0-0/02-clickable-html-data-events.md"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"id": "nested-event-bubbling",
|
|
20
|
+
"description": "Add bubble: true only to nested events whose outer event reads a value the inner event sets, copy AgGrid onRowClick state setup into cell control events that relied on it, and report the nested events left with the new innermost-only behaviour.",
|
|
21
|
+
"path": "v7-0-0/03-nested-event-bubbling.md"
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
},
|
|
3
25
|
{
|
|
4
26
|
"version": "6.0.0",
|
|
5
27
|
"from": ">=5.0.0 <6.0.0",
|
|
6
|
-
"description": "Vite + Hono server migration (plugin ESM exports, Auth.js imports, provider-neutral file blocks)",
|
|
28
|
+
"description": "Vite + Hono server migration (plugin ESM exports, Auth.js imports, provider-neutral file blocks, request timeout, plugin type overrides)",
|
|
7
29
|
"codemods": [
|
|
8
30
|
{
|
|
9
31
|
"id": "migrate-plugin-packages",
|
|
@@ -14,6 +36,16 @@
|
|
|
14
36
|
"id": "s3-blocks-to-file-blocks",
|
|
15
37
|
"description": "Optional: rename the deprecated S3UploadButton/S3UploadPhoto/S3UploadDragger/S3Download blocks to the provider-neutral Upload/UploadPhoto/UploadDragger/Download blocks, and s3PostPolicyRequestId/s3GetPolicyRequestId to uploadPolicyRequestId/downloadPolicyRequestId (also on TiptapInput, TiptapMentionInput, and AgentChat attachments). The aliases keep working; this silences deprecation warnings.",
|
|
16
38
|
"path": "v6-0-0/02-s3-blocks-to-file-blocks.md"
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"id": "request-timeout",
|
|
42
|
+
"description": "Add config.requestTimeout: 0 to keep the v5 request duration. v6 cuts requests off after 30 seconds by default (v5 had no timeout), and a cut-off request shows a generic error while the rest of the page renders from the requests that finished.",
|
|
43
|
+
"path": "v6-0-0/03-request-timeout.md"
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
"id": "report-type-overrides",
|
|
47
|
+
"description": "Report-only: after a build, list custom plugin types that override a Lowdefy built-in type of the same name. A plugin holding a v5 copy of a built-in keeps its v5 behaviour and can break v6 blocks without an error. Each override needs author review: keep, delete the copy, or rename.",
|
|
48
|
+
"path": "v6-0-0/04-report-type-overrides.md"
|
|
17
49
|
}
|
|
18
50
|
]
|
|
19
51
|
},
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Migration: Keep the v5 Request Duration with `config.requestTimeout`
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
Lowdefy v6 adds a server-side request timeout. `config.requestTimeout` in `lowdefy.yaml` (milliseconds) defaults to **30000** (30 seconds) and applies to every server route except agent streaming, MCP and websockets: requests, API endpoints, cron and detached endpoint runs, auth and page routes. Set it to `0` to disable it.
|
|
6
|
+
|
|
7
|
+
Lowdefy v5 had no timeout. A request ran until it finished or until the host's own limit stopped it (for example Vercel's function `maxDuration`). So a request that took 30–60 seconds in v5, such as a heavy MongoDB aggregation, a report query or a slow external API, **fails in v6**.
|
|
8
|
+
|
|
9
|
+
The failure is easy to miss:
|
|
10
|
+
|
|
11
|
+
- The request returns a generic server error, so the user sees "Something went wrong."
|
|
12
|
+
- The rest of the page still renders. A page that combines several requests (summary cards, totals) shows results computed from the requests that finished, and the numbers can look plausible.
|
|
13
|
+
- Dev servers from before this codemod was added don't apply the timeout, so the failure only shows up under `lowdefy build` + `lowdefy start` or on the deployed app.
|
|
14
|
+
|
|
15
|
+
This codemod keeps the v5 behaviour by setting `requestTimeout: 0`, and gives the app author what they need to choose a real limit later.
|
|
16
|
+
|
|
17
|
+
## Scope
|
|
18
|
+
|
|
19
|
+
`app` — the app's `lowdefy.yaml` (or `lowdefy.yml`), including a `config:` section pulled in with `_ref`.
|
|
20
|
+
|
|
21
|
+
## What to Do
|
|
22
|
+
|
|
23
|
+
### Step 1: Check whether the app already sets a timeout
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
grep -rn 'requestTimeout' lowdefy.yaml lowdefy.yml 2>/dev/null
|
|
27
|
+
grep -rn 'requestTimeout' --include='*.yaml' --include='*.yml' --include='*.njk' . | grep -v node_modules
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
If `config.requestTimeout` is already set (any value), **stop — no changes needed**. The author has already chosen a limit.
|
|
31
|
+
|
|
32
|
+
### Step 2: Add `requestTimeout: 0` to `config`
|
|
33
|
+
|
|
34
|
+
Add the key under `config:` in `lowdefy.yaml`, with a comment so the choice is visible:
|
|
35
|
+
|
|
36
|
+
```yaml
|
|
37
|
+
config:
|
|
38
|
+
# Lowdefy v6 defaults to a 30s request timeout; v5 had none. 0 keeps the v5 behaviour, so the
|
|
39
|
+
# host's own limit (e.g. Vercel maxDuration) is the only cap. Set a value in ms to cap requests.
|
|
40
|
+
requestTimeout: 0
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
If `config:` is a `_ref` to another file, add the key in that file. If the app has no `config:` section, create one.
|
|
44
|
+
|
|
45
|
+
### Step 3: Report
|
|
46
|
+
|
|
47
|
+
Tell the app author:
|
|
48
|
+
|
|
49
|
+
- `config.requestTimeout: 0` was added to keep the v5 behaviour.
|
|
50
|
+
- The timeout protects against requests that hang on an upstream call and run to the host's limit, which is billed compute on serverless hosts. On a host with its own limit, `0` costs the same as v5 did.
|
|
51
|
+
- To choose a real limit, find the app's slowest successful requests in the host's logs (request duration per endpoint or request id). Set `requestTimeout` comfortably above the slowest one, or keep `0` if some requests legitimately run long.
|
|
52
|
+
|
|
53
|
+
### Step 4: Verify
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
lowdefy build
|
|
57
|
+
lowdefy start
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Open the pages with the heaviest requests (reports, dashboards, validation pages) and check that every request succeeds.
|
|
61
|
+
|
|
62
|
+
## Files to Check
|
|
63
|
+
|
|
64
|
+
- `lowdefy.yaml` / `lowdefy.yml` — the `config:` section
|
|
65
|
+
- Any file `config:` is loaded from with `_ref`
|
|
66
|
+
|
|
67
|
+
## Examples
|
|
68
|
+
|
|
69
|
+
### Before
|
|
70
|
+
|
|
71
|
+
```yaml
|
|
72
|
+
lowdefy: 6.0.0
|
|
73
|
+
name: My App
|
|
74
|
+
|
|
75
|
+
config:
|
|
76
|
+
homePageId: dashboard
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### After
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
lowdefy: 6.0.0
|
|
83
|
+
name: My App
|
|
84
|
+
|
|
85
|
+
config:
|
|
86
|
+
homePageId: dashboard
|
|
87
|
+
# Lowdefy v6 defaults to a 30s request timeout; v5 had none. 0 keeps the v5 behaviour, so the
|
|
88
|
+
# host's own limit (e.g. Vercel maxDuration) is the only cap. Set a value in ms to cap requests.
|
|
89
|
+
requestTimeout: 0
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Edge Cases
|
|
93
|
+
|
|
94
|
+
- **Agent, MCP and websocket routes** are exempt from the timeout whatever the value, so apps that only have long-running agents need no change for those.
|
|
95
|
+
- **Hosts without a function limit** (Docker, a long-lived Node host): with `0`, a request that hangs upstream runs until the upstream call gives up. If that matters, set a limit instead of `0`.
|
|
96
|
+
- **Multiple apps in one repo:** each app has its own `lowdefy.yaml`. Apply the change to each one.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Migration: Report Plugin Types That Override Lowdefy's Built-in Types
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
When a custom plugin exports a block, action, connection, request, operator or auth type with the same name as one of Lowdefy's built-in types, **the plugin's type wins**. The build merges the default types first and the app's plugins over them, so the plugin replaces the built-in type everywhere, without a warning.
|
|
6
|
+
|
|
7
|
+
Some overrides are deliberate. For example, `@lowdefy/community-plugin-mongodb` replaces the core MongoDB connection and request types. The risky case is a plugin that holds a **copy of a v5 built-in type**, often made to patch one detail. In v6 the rest of Lowdefy moved on, and the copy keeps its v5 behaviour:
|
|
8
|
+
|
|
9
|
+
- A local copy of the v5 `AwsS3Bucket` connection returned the v5 upload policy (`{ url, fields }`). The v6 upload blocks read `key` and `bucket` from the top level of the policy. Image drop and paste in `TiptapInput` threw, and `S3UploadDragger` saved files without the key needed to download them. The build and the upload itself both succeeded, so nothing pointed at the plugin.
|
|
10
|
+
|
|
11
|
+
This codemod is **report-only**: it lists every override, and the app author decides what to do with each one.
|
|
12
|
+
|
|
13
|
+
## Scope
|
|
14
|
+
|
|
15
|
+
`app` — the app's build output. Run it after a successful `lowdefy build`.
|
|
16
|
+
|
|
17
|
+
## What to Do
|
|
18
|
+
|
|
19
|
+
### Step 1: Build the app
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
lowdefy build
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The build writes the types the app actually uses, and the package each one resolved to, to `build/types.json` in the server directory (`.lowdefy/server` by default; use the `--server-directory` passed to `lowdefy build` if set).
|
|
26
|
+
|
|
27
|
+
### Step 2: List types that override a built-in type
|
|
28
|
+
|
|
29
|
+
Save this script as `find-type-overrides.mjs` next to `lowdefy.yaml` and run it with the server directory:
|
|
30
|
+
|
|
31
|
+
```javascript
|
|
32
|
+
import fs from 'node:fs';
|
|
33
|
+
import path from 'node:path';
|
|
34
|
+
|
|
35
|
+
const server = path.resolve(process.argv[2] ?? '.lowdefy/server');
|
|
36
|
+
const { default: core } = await import(
|
|
37
|
+
path.join(server, 'node_modules/@lowdefy/build/dist/defaultTypesMap.js')
|
|
38
|
+
);
|
|
39
|
+
const used = JSON.parse(fs.readFileSync(path.join(server, 'build/types.json'), 'utf8'));
|
|
40
|
+
|
|
41
|
+
function isPlainObject(value) {
|
|
42
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function walk(usedMap, coreMap, where) {
|
|
46
|
+
Object.entries(usedMap).forEach(([name, entry]) => {
|
|
47
|
+
if (!isPlainObject(entry)) return;
|
|
48
|
+
if (typeof entry.package !== 'string') {
|
|
49
|
+
walk(entry, coreMap?.[name] ?? {}, `${where}.${name}`);
|
|
50
|
+
return;
|
|
51
|
+
}
|
|
52
|
+
const coreEntry = coreMap?.[name];
|
|
53
|
+
if (coreEntry && coreEntry.package !== entry.package) {
|
|
54
|
+
console.log(`${where}.${name}: ${entry.package} overrides ${coreEntry.package}`);
|
|
55
|
+
}
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
walk(used, core, 'types');
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
node find-type-overrides.mjs .lowdefy/server
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Each line names a type, the plugin that provides it, and the built-in package it replaces:
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
types.connections.AwsS3Bucket: @acme/plugin-local overrides @lowdefy/plugin-aws
|
|
70
|
+
types.blocks.TreeSelector: @acme/plugin-local overrides @lowdefy/blocks-antd
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Delete the script afterwards.
|
|
74
|
+
|
|
75
|
+
### Step 3: Classify each override
|
|
76
|
+
|
|
77
|
+
For every line, find the plugin's source for that type and decide which case it is:
|
|
78
|
+
|
|
79
|
+
| Case | How to tell | Recommendation |
|
|
80
|
+
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| **Deliberate replacement** from a maintained plugin | A published plugin whose purpose is to replace the built-in, e.g. `@lowdefy/community-plugin-mongodb` | Keep it. Check the plugin has a release for this Lowdefy major version. |
|
|
82
|
+
| **Copy of a built-in** | Same name, and the source is close to the v5 built-in (often with an old SDK, e.g. `aws-sdk` v2 instead of `@aws-sdk/*` v3) | **Delete the copy** so the v6 built-in is used. First check the app only uses properties the v6 built-in supports (its schema is in the built-in package). |
|
|
83
|
+
| **Different type that shares a name** | Unrelated behaviour that happens to share a built-in's name | **Rename** the plugin type (e.g. prefix it) and update the app's config to use the new name. |
|
|
84
|
+
|
|
85
|
+
### Step 4: Report
|
|
86
|
+
|
|
87
|
+
Produce one entry per override:
|
|
88
|
+
|
|
89
|
+
- The type and its kind (block, connection, request, ...).
|
|
90
|
+
- The plugin that provides it and the built-in package it replaces.
|
|
91
|
+
- The case from Step 3 and the recommended action.
|
|
92
|
+
- For a copy: the differences from the v6 built-in that the app relies on, if any.
|
|
93
|
+
|
|
94
|
+
Do not delete or rename anything without the app author's approval. A plugin may override a type on purpose, for a reason the source doesn't show.
|
|
95
|
+
|
|
96
|
+
### Step 5: Verify
|
|
97
|
+
|
|
98
|
+
After any deletions or renames, rebuild and rerun the script. Only the overrides the author chose to keep should remain. Then test the features that use each changed type, especially file uploads and downloads for connection and request types.
|
|
99
|
+
|
|
100
|
+
## Files to Check
|
|
101
|
+
|
|
102
|
+
- `build/types.json` in the server directory — the resolved package for every used type
|
|
103
|
+
- `node_modules/@lowdefy/build/dist/defaultTypesMap.js` in the server directory — Lowdefy's built-in types
|
|
104
|
+
- Each custom plugin's `types.js` and the source of every overriding type
|
|
105
|
+
|
|
106
|
+
## Edge Cases
|
|
107
|
+
|
|
108
|
+
- **Only used types are reported.** `build/types.json` lists types the app's config uses. A plugin type that shadows a built-in but isn't used anywhere doesn't appear, and doesn't affect the app.
|
|
109
|
+
- **Community plugins** are listed too. Their overrides are usually deliberate, so check the plugin's v6 compatibility rather than removing them.
|
|
110
|
+
- **Multiple apps in one repo:** run the script for each app's server directory.
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
# Migration: react-icons Names → Lucide Icons
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
Lowdefy v7 replaces react-icons with [Lucide](https://lucide.dev). Every icon name in an app's
|
|
6
|
+
config is resolved and bundled by the build, and a name the build cannot resolve at an icon
|
|
7
|
+
position **fails the build**. react-icons names (`AiOutlineUser`, `MdLocationOn`, `LuPencil`, …)
|
|
8
|
+
are no longer icon names unless the app installs the react-icons compatibility set (see
|
|
9
|
+
[Fallback](#fallback-the-react-icons-compatibility-set)).
|
|
10
|
+
|
|
11
|
+
An icon name now takes one of three forms:
|
|
12
|
+
|
|
13
|
+
| Form | Example | Meaning |
|
|
14
|
+
| ------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| **Semantic** | `edit`, `delete`, `chevron-down` | A lowercase kebab-case name Lowdefy maps to an icon. Apps can re-map it in `theme.icons.aliases`. Prefer these. |
|
|
16
|
+
| **Set name** | `Pencil`, `CreditCard` | A Lucide icon, PascalCase, exactly as Lucide names it. |
|
|
17
|
+
| **Qualified** | `lucide:Pencil`, `react-icons:AiOutlineUser` | An icon in a named icon set. |
|
|
18
|
+
|
|
19
|
+
This migration rewrites react-icons names (and stale Ant Design names such as `HomeOutlined`,
|
|
20
|
+
which have never rendered anything in Lowdefy) to semantic or Lucide names, using a migration
|
|
21
|
+
table that ships with this codemod.
|
|
22
|
+
|
|
23
|
+
## The Migration Table
|
|
24
|
+
|
|
25
|
+
The table is `v7-0-0/react-icons-to-lucide.json` in the `@lowdefy/codemods` package. `lowdefy
|
|
26
|
+
upgrade` downloads the package to `.lowdefy/codemods/` in the app's config directory, so the
|
|
27
|
+
table is at:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
.lowdefy/codemods/v7-0-0/react-icons-to-lucide.json
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
(If that folder is missing, download it from
|
|
34
|
+
`https://unpkg.com/@lowdefy/codemods@latest/v7-0-0/react-icons-to-lucide.json`.)
|
|
35
|
+
|
|
36
|
+
Its shape:
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"icons": {
|
|
41
|
+
"AiOutlineDelete": "delete",
|
|
42
|
+
"AiOutlineCreditCard": "CreditCard",
|
|
43
|
+
"HomeOutlined": "home",
|
|
44
|
+
"LuTrash2": "Trash"
|
|
45
|
+
},
|
|
46
|
+
"review": {
|
|
47
|
+
"AiOutlineAlert": "antd Alert is an alarm light; Siren is the closest Lucide glyph.",
|
|
48
|
+
"FaWhatsapp": "Brand logo; Lucide has no brand icons, MessageCircle is a generic stand-in. Use the react-icons compatibility set to keep the logo."
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- `icons` maps each old name to its new name. A lowercase value is a **semantic name**; a
|
|
54
|
+
PascalCase value is a **Lucide name**. Every value resolves in Lowdefy v7.
|
|
55
|
+
- `review` lists the entries where the new glyph is a judgement call or a known loss (filled
|
|
56
|
+
and two-tone glyphs become outline, brand logos become generic glyphs, file-type glyphs such
|
|
57
|
+
as Word/PDF/Excel become generic file glyphs). The rewrite still applies; the author reviews
|
|
58
|
+
the result.
|
|
59
|
+
- The table covers every Ant Design name in react-icons (`AiOutline*`, `AiFill*`, `AiTwotone*`),
|
|
60
|
+
every `Lu*` name, and the names from other packs seen in real apps.
|
|
61
|
+
|
|
62
|
+
**Load the table and apply it with a script** (Node is available in every Lowdefy project).
|
|
63
|
+
Apps often have thousands of icon occurrences; do not rewrite them by hand.
|
|
64
|
+
|
|
65
|
+
## What to Do
|
|
66
|
+
|
|
67
|
+
### 1. Find every icon name occurrence
|
|
68
|
+
|
|
69
|
+
An icon name is always a **whole string value**. Match a name only as a whole token:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
\b(Ai|Bi|Bs|Cg|Ci|Di|Fa|Fc|Fi|Gi|Go|Gr|Hi|Im|Io|Lia|Lu|Md|Pi|Ri|Rx|Si|Sl|Tb|Tfi|Ti|Vsc|Wi)[A-Z0-9][A-Za-z0-9]*\b
|
|
73
|
+
\b[A-Z][A-Za-z]*(Outlined|Filled|TwoTone)\b
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Look in all of these places:
|
|
77
|
+
|
|
78
|
+
| Where | Example |
|
|
79
|
+
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
80
|
+
| YAML config (`.yaml`, `.yml`) | `icon: AiOutlineEdit`, `name: AiOutlineHome`, `- AiOutlineUser` |
|
|
81
|
+
| Nunjucks templates (`.njk`, `.yaml.njk`) | `icon: AiOutlineSave` — these often do not parse as YAML, so treat them as text |
|
|
82
|
+
| JSON files (`.json`) | `"icon": "AiOutlineUser"` |
|
|
83
|
+
| `_js` code strings | `return 'AiOutlineCheck'` or `return "AiOutlineCheck"` inside `_js:` blocks and `.js` files referenced by `_ref` |
|
|
84
|
+
| HTML strings | `<span data-icon="AiOutlineUser"></span>` |
|
|
85
|
+
| Local plugin JS (custom blocks/actions) | string literals `'AiOutlineUser'` and `meta.icons: ['AiOutlineUser']` |
|
|
86
|
+
| `theme.icons.aliases` targets | `invoice: LuReceipt` |
|
|
87
|
+
| `theme.icons.include` | `- AiOutlineFlag` |
|
|
88
|
+
| Enum/global maps, `_if`/`_get` branches, module vars, request pipelines (`$switch` `then:` values) | `then: AiOutlineCheckCircle` |
|
|
89
|
+
|
|
90
|
+
Skip `node_modules/`, `.lowdefy/`, `.git/` and build output folders.
|
|
91
|
+
|
|
92
|
+
### 2. Rewrite each name with the table
|
|
93
|
+
|
|
94
|
+
For each match that is a key of `table.icons`, replace the name with its value, preserving the
|
|
95
|
+
surrounding text exactly (quotes, indentation, YAML style).
|
|
96
|
+
|
|
97
|
+
- **Prefer semantic names.** The table already chooses a semantic name wherever one means
|
|
98
|
+
exactly the same thing (`AiOutlineDelete` → `delete`, `AiOutlineHome` → `home`,
|
|
99
|
+
`AiOutlinePlusCircle` → `add-circle`). Keep them; do not expand them to Lucide names.
|
|
100
|
+
- **Stale Ant Design names** (`HomeOutlined`, `CheckOutlined`, `UserOutlined`, …) are in the
|
|
101
|
+
table too and map to semantic names where one fits. Only rewrite them where they are string
|
|
102
|
+
values in config or string literals. **Never** rewrite identifiers in JS `import` statements
|
|
103
|
+
or JSX (e.g. `import { HomeOutlined } from '@ant-design/icons'`) — those are real components.
|
|
104
|
+
- **`Lu*` names** map by dropping `Lu`, normalised to Lucide's current canonical name
|
|
105
|
+
(`LuPencil` → `Pencil`, `LuTrash2` → `Trash`, `LuFilter` → `Funnel`). The table has all of
|
|
106
|
+
them.
|
|
107
|
+
- **`theme.icons.aliases` targets must stay set or qualified names**, never semantic names
|
|
108
|
+
(an alias cannot point at another semantic name). When the table gives a semantic value for
|
|
109
|
+
an alias target, write the semantic name's Lucide target instead (see the list below), e.g.
|
|
110
|
+
`invoice: AiOutlineFileText` → `invoice: FileText`, `trash: LuTrash2` → `trash: Trash`.
|
|
111
|
+
- **Names not in the table.** Do not guess. Find the Lucide icon that matches by meaning (the
|
|
112
|
+
v7 dev server serves `GET /lowdefy-docs/icons?q=<words>` and the MCP tool
|
|
113
|
+
`lowdefy_search_icons`; or search https://lucide.dev/icons) and use its PascalCase name.
|
|
114
|
+
If nothing fits, leave the name and list it in the report — it can keep working through the
|
|
115
|
+
compatibility set.
|
|
116
|
+
- **Qualified names stay as they are.** A name after a set id and a colon
|
|
117
|
+
(`react-icons:FaWhatsapp`) was chosen on purpose to keep that glyph through the compatibility
|
|
118
|
+
set. The patterns above also match the part after the colon; never rewrite it, so running the
|
|
119
|
+
migration again changes nothing.
|
|
120
|
+
|
|
121
|
+
Semantic names and their Lucide targets (needed for `theme.icons.aliases` targets):
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
add Plus · add-circle CirclePlus · arrow-down ArrowDown · arrow-left ArrowLeft · arrow-right ArrowRight
|
|
125
|
+
arrow-up ArrowUp · attach Paperclip · bell Bell · bold Bold · bot Bot · calendar Calendar · camera Camera
|
|
126
|
+
chart ChartColumn · check Check · check-circle CircleCheck · chevron-down ChevronDown
|
|
127
|
+
chevron-left ChevronLeft · chevron-right ChevronRight · chevron-up ChevronUp · chevrons-left ChevronsLeft
|
|
128
|
+
chevrons-right ChevronsRight · clear CircleX · clock Clock · close X · close-circle CircleX · copy Copy
|
|
129
|
+
delete Trash · document FileText · download Download · drag GripVertical · edit Pencil · error CircleX
|
|
130
|
+
external-link ExternalLink · file File · filter Funnel · folder Folder · globe Globe · grid LayoutGrid
|
|
131
|
+
heart Heart · help CircleQuestionMark · hide EyeOff · highlight Highlighter · history RotateCcwClock
|
|
132
|
+
home House · image Image · info Info · italic Italic · link Link · list List · loading LoaderCircle
|
|
133
|
+
location MapPin · lock Lock · login LogIn · logout LogOut · mail Mail · menu Menu · message MessageSquare
|
|
134
|
+
minus Minus · more Ellipsis · more-vertical EllipsisVertical · phone Phone · print Printer
|
|
135
|
+
refresh RefreshCw · remove CircleMinus · save Save · search Search · send Send · settings Settings
|
|
136
|
+
share Share2 · sidebar-collapse PanelLeftClose · sidebar-expand PanelLeftOpen · sort ArrowUpDown
|
|
137
|
+
star Star · strikethrough Strikethrough · success CircleCheck · tag Tag · unlock LockOpen · upload Upload
|
|
138
|
+
user User · users Users · view Eye · warning TriangleAlert
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### 3. Report what needs a human
|
|
142
|
+
|
|
143
|
+
Do not change data, and do not change anything in this step. Produce a report with:
|
|
144
|
+
|
|
145
|
+
1. **Review entries.** Every rewritten name that is a key of `table.review`: old name, new
|
|
146
|
+
name, the review note, and each file (and line) it was rewritten in. Group by old name.
|
|
147
|
+
2. **Unmapped names.** Every icon-like name found that is not in the table, with its locations.
|
|
148
|
+
3. **Runtime-only icon sources.** Icon positions whose value comes from data rather than
|
|
149
|
+
config, so no text rewrite can reach it:
|
|
150
|
+
|
|
151
|
+
- `icon:`, `name:` (Icon block), `prefixIcon:`, `suffixIcon:` and other `*Icon:` properties,
|
|
152
|
+
menu link `icon:` and HTML `data-icon` values that are `_state`, `_payload`,
|
|
153
|
+
`_request`, `_input`, `_url_query`, `_user`, `_global` or `_get` with `from:` one of those;
|
|
154
|
+
- request pipelines (for example MongoDB `$switch`, `$cond`, `$project`) that return an
|
|
155
|
+
icon field built from document fields rather than literals;
|
|
156
|
+
- enum lists used as an icon picker whose chosen value is saved to a database.
|
|
157
|
+
|
|
158
|
+
For each, note that stored or computed icon names must either be migrated in the data
|
|
159
|
+
(outside this codemod, using the same table) or keep working through the compatibility set,
|
|
160
|
+
and that names only known at runtime must be listed in `theme.icons.include` so the build
|
|
161
|
+
bundles them.
|
|
162
|
+
|
|
163
|
+
4. **Direct react-icons imports in local plugins** (`import … from 'react-icons/…'`). These
|
|
164
|
+
stop working in v7 because react-icons is no longer installed. The plugin should render
|
|
165
|
+
`components.Icon` with a semantic or Lucide name instead (and list the names in the
|
|
166
|
+
block's `meta.icons`), or import from `lucide-react` directly.
|
|
167
|
+
5. **Totals:** files changed, occurrences rewritten, how many to semantic names and how many
|
|
168
|
+
to Lucide names.
|
|
169
|
+
|
|
170
|
+
## Fallback: the react-icons Compatibility Set
|
|
171
|
+
|
|
172
|
+
`@lowdefy/icons-react-icons` is an icon-set plugin holding every react-icons 5.6.0 icon under
|
|
173
|
+
its old name. Recommend it in the report when the app:
|
|
174
|
+
|
|
175
|
+
- stores icon names in a database (names users picked, records with an `icon` field),
|
|
176
|
+
- needs brand logos Lucide does not have (`FaWhatsapp`, `AiOutlineGithub`, `SiStripe`, …), or
|
|
177
|
+
- has unmapped names that should keep their exact glyph.
|
|
178
|
+
|
|
179
|
+
```yaml
|
|
180
|
+
plugins:
|
|
181
|
+
- name: '@lowdefy/icons-react-icons'
|
|
182
|
+
version: 7.0.0
|
|
183
|
+
|
|
184
|
+
theme:
|
|
185
|
+
icons:
|
|
186
|
+
set: react-icons # old names resolve unqualified, Lucide and semantic names keep working
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Without `theme.icons.set: react-icons`, old names still resolve when qualified:
|
|
190
|
+
`react-icons:AiOutlineUser`. A single brand logo can therefore be kept with
|
|
191
|
+
`icon: react-icons:FaWhatsapp` while the rest of the app moves to Lucide.
|
|
192
|
+
|
|
193
|
+
## Examples
|
|
194
|
+
|
|
195
|
+
### Before
|
|
196
|
+
|
|
197
|
+
```yaml
|
|
198
|
+
- id: save_button
|
|
199
|
+
type: Button
|
|
200
|
+
properties:
|
|
201
|
+
title: Save
|
|
202
|
+
icon: AiOutlineSave
|
|
203
|
+
- id: breadcrumb
|
|
204
|
+
type: Breadcrumb
|
|
205
|
+
properties:
|
|
206
|
+
list:
|
|
207
|
+
- label: Home
|
|
208
|
+
icon: AiOutlineHome
|
|
209
|
+
pageId: home
|
|
210
|
+
- label: Contacts
|
|
211
|
+
icon: AiOutlineContacts
|
|
212
|
+
- id: status_icon
|
|
213
|
+
type: Icon
|
|
214
|
+
properties:
|
|
215
|
+
name:
|
|
216
|
+
_if:
|
|
217
|
+
test:
|
|
218
|
+
_state: done
|
|
219
|
+
then: AiFillCheckCircle
|
|
220
|
+
else: AiOutlineClockCircle
|
|
221
|
+
- id: legacy
|
|
222
|
+
type: Button
|
|
223
|
+
properties:
|
|
224
|
+
icon: HomeOutlined
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### After
|
|
228
|
+
|
|
229
|
+
```yaml
|
|
230
|
+
- id: save_button
|
|
231
|
+
type: Button
|
|
232
|
+
properties:
|
|
233
|
+
title: Save
|
|
234
|
+
icon: save
|
|
235
|
+
- id: breadcrumb
|
|
236
|
+
type: Breadcrumb
|
|
237
|
+
properties:
|
|
238
|
+
list:
|
|
239
|
+
- label: Home
|
|
240
|
+
icon: home
|
|
241
|
+
pageId: home
|
|
242
|
+
- label: Contacts
|
|
243
|
+
icon: Contact
|
|
244
|
+
- id: status_icon
|
|
245
|
+
type: Icon
|
|
246
|
+
properties:
|
|
247
|
+
name:
|
|
248
|
+
_if:
|
|
249
|
+
test:
|
|
250
|
+
_state: done
|
|
251
|
+
then: check-circle
|
|
252
|
+
else: clock
|
|
253
|
+
- id: legacy
|
|
254
|
+
type: Button
|
|
255
|
+
properties:
|
|
256
|
+
icon: home
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
`AiFillCheckCircle` is a `review` entry (filled glyph becomes outline), so it goes in the report.
|
|
260
|
+
|
|
261
|
+
### `_js` and local plugins
|
|
262
|
+
|
|
263
|
+
```yaml
|
|
264
|
+
# Before
|
|
265
|
+
icon:
|
|
266
|
+
_js: |
|
|
267
|
+
return state.approved ? 'AiOutlineCheck' : "AiOutlineClose";
|
|
268
|
+
# After
|
|
269
|
+
icon:
|
|
270
|
+
_js: |
|
|
271
|
+
return state.approved ? 'check' : "close";
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
```javascript
|
|
275
|
+
// Before — local plugin block
|
|
276
|
+
MyBlock.meta = { category: 'display', icons: ['AiOutlineUser', 'LuPencil'] };
|
|
277
|
+
// After
|
|
278
|
+
MyBlock.meta = { category: 'display', icons: ['user', 'Pencil'] };
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### `theme.icons.aliases`
|
|
282
|
+
|
|
283
|
+
```yaml
|
|
284
|
+
# Before
|
|
285
|
+
theme:
|
|
286
|
+
icons:
|
|
287
|
+
aliases:
|
|
288
|
+
invoice: LuReceipt
|
|
289
|
+
remove-row: AiOutlineDelete
|
|
290
|
+
# After — targets stay Lucide names
|
|
291
|
+
theme:
|
|
292
|
+
icons:
|
|
293
|
+
aliases:
|
|
294
|
+
invoice: Receipt
|
|
295
|
+
remove-row: Trash
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Edge Cases
|
|
299
|
+
|
|
300
|
+
- **Block `type:` values are not icons.** Lucide has icons named like some block types
|
|
301
|
+
(`Anchor`, `Badge`, `Calendar`, `Menu`, `Tag`, …). Only rewrite names that match the patterns
|
|
302
|
+
above; never touch `type:` values.
|
|
303
|
+
- **`PiSquare` is also a Lucide name.** In react-icons it is the Phosphor square; in Lucide it
|
|
304
|
+
is a pi sign in a square, and v7 resolves it to Lucide with no build error. It is not in the
|
|
305
|
+
table. Where the app meant the square, rewrite it to `Square`, and list it in the report.
|
|
306
|
+
- **Names inside prose** (descriptions, markdown, help text) that mention an icon for a human
|
|
307
|
+
reader can be rewritten too, but list them in the report rather than assuming.
|
|
308
|
+
- **Duplicate meaning after rewrite.** Different old names can map to the same new name
|
|
309
|
+
(`AiOutlineClockCircle` and `AiOutlineFieldTime` both relate to time). That is expected.
|
|
310
|
+
- **Tests and snapshots** in local plugins that assert old icon names need the same rewrite.
|
|
311
|
+
- **Data stays untouched.** Never modify database documents, seed files that are loaded into a
|
|
312
|
+
database at runtime, or fixtures, unless the author asks; list them in the report instead.
|
|
313
|
+
|
|
314
|
+
## Verification
|
|
315
|
+
|
|
316
|
+
1. No react-icons names or stale Ant Design names remain in config (the only allowed matches
|
|
317
|
+
are ones deliberately qualified as `react-icons:…`, listed in the report, or inside JS
|
|
318
|
+
`import` statements for `@ant-design/icons`):
|
|
319
|
+
|
|
320
|
+
```
|
|
321
|
+
grep -rnE '\b(Ai|Bi|Bs|Cg|Ci|Di|Fa|Fc|Fi|Gi|Go|Gr|Hi|Im|Io|Lia|Lu|Md|Pi|Ri|Rx|Si|Sl|Tb|Tfi|Ti|Vsc|Wi)[A-Z0-9][A-Za-z0-9]*\b|\b[A-Z][A-Za-z]*(Outlined|Filled|TwoTone)\b' \
|
|
322
|
+
--include='*.yaml' --include='*.yml' --include='*.njk' --include='*.json' --include='*.js' \
|
|
323
|
+
--exclude-dir=node_modules --exclude-dir=.lowdefy .
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
2. Run `lowdefy build`. Any icon name that still does not resolve fails the build with its
|
|
327
|
+
config location and a suggestion; fix each one with the table or a Lucide search.
|