@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lowdefy/codemods",
3
- "version": "6.0.0",
3
+ "version": "7.0.0",
4
4
  "description": "Codemod scripts and migration prompts for Lowdefy version upgrades",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
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
  },
@@ -131,7 +131,7 @@ Server-side plugin files load as Node ESM. CJS dists still load through Node's i
131
131
  "./*": "./dist/*"
132
132
  },
133
133
  "dependencies": {
134
- "@auth/core": "0.41.2"
134
+ "@auth/core": "0.41.3"
135
135
  }
136
136
  }
137
137
  ```
@@ -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.