Lowdefy CLI

5.1.0 · active · verified Wed Apr 22

Lowdefy is an open-source, low-code framework for building web applications and server-side APIs primarily through declarative YAML or JSON configuration. It abstracts much of the underlying JavaScript, TypeScript, and UI component boilerplate, allowing developers to define application logic, UI layouts (leveraging Ant Design), and data connections efficiently. The `lowdefy` npm package provides the Command Line Interface (CLI) tool essential for initializing projects, running a development server, and building applications. As of version 5.1.0, Lowdefy maintains an active release cadence, with frequent updates delivering new features like Ant Design v6 integration, enhanced theme token management, and improved dark mode support. Its key differentiators include its strong emphasis on YAML-driven configuration, deep integration with the Ant Design ecosystem, and comprehensive support for full-stack application development, including server-side APIs and user authentication, without extensive custom coding.

Common errors

```
Error: A "lowdefy.yaml" file already exists: Try running the command in a new directory or consider deleting the lowdefy.yaml file in your current working directory.
```
cause Attempting to initialize a new Lowdefy project (`npx lowdefy@latest init`) in a directory that already contains a `lowdefy.yaml` file.

fix Execute `npx lowdefy@latest init` in an empty directory, or remove the existing `lowdefy.yaml` file if you intend to overwrite it.
```
Dev server hangs indefinitely at "Building config..."
```
cause This issue was specifically observed in older v4.x versions when a page's entire YAML content was a `_ref`, causing an infinite loop during configuration processing.

fix Upgrade Lowdefy to version `v4.7.2` or newer, which includes a fix for this dev server hang. Review `_ref` usage for circular dependencies. (Found in release notes, no specific cite for problem, but fix in v4.7.2)
```
TypeError in icon `formatTitle`
```
cause A bug in older versions of `@lowdefy/blocks-antd` could lead to a `TypeError` when processing icon titles.

fix Upgrade Lowdefy and its related `@lowdefy/*` packages to `v4.5.2` or newer to resolve this bug. (Found in release notes, no specific cite for problem, but fix in v4.5.2)
```
LOWDEFY_SECRET_EXAMPLES_MDB="{{ your_mongodb_connection_uri }}" - Connection string issues or payload size exceeded.
```
cause Incorrectly configured MongoDB connection URI, or in older v3 versions, sending large `_state`, `_global`, `_input`, `_url_query`, or `_event` objects directly with requests, leading to payload size limits.

fix Ensure `.env` variables for database URIs are correctly formatted and accessible. For payload size issues, especially when migrating from v3 to v4, use the `payload` property explicitly in requests to control what data is sent to the server. The `_payload` operator should then be used server-side to access this data.

Warnings

breaking The `_moment` operator has been removed and replaced with `_dayjs` in v5. All applications using `_moment` must migrate to `_dayjs` and update their date format strings if custom formats were used.
Fix: Globally find and replace `_moment` with `_dayjs` in your YAML configuration files. Consider running `lowdefy upgrade` CLI for automated migration.
breaking The entire styling system underwent a significant overhaul in v5, migrating from Less/Emotion to CSS-in-JS with Tailwind CSS. Custom Less styles (e.g., `styles.less`) and direct usage of Less variables like `@primary-color` are no longer supported.
Fix: Rewrite custom styles using CSS-in-JS with Tailwind classes or apply them via `theme.antd.token` and `style: { .key }` properties. Migrate Less variables to Ant Design v6 theme tokens.
breaking The main configuration file `lowdefy.config.yaml` has been renamed to `lowdefy.yaml` in v5. Projects upgrading from v4 must update their file names.
Fix: Rename `lowdefy.config.yaml` to `lowdefy.yaml` in your project root.
breaking Several component theme and style properties have been removed in v5, including `header.theme`, `sider.theme`, and `menu.theme` from blocks like `PageSiderMenu`, `PageHeaderMenu`, `Header`, and `Sider`. Direct `style` properties on these components were also removed.
Fix: Remove deprecated theme properties. For styling specific parts of blocks, use the new `style: { .key: {...} }` syntax. Dark mode is now automatic via CSS variables.
breaking The `Comment` block has been entirely removed in v5 (following Ant Design v5 changes).
Fix: Refactor applications using the `Comment` block to compose functionality with `Card`, `Flex`, `Avatar`, and `Paragraph` blocks instead.
gotcha Lowdefy CLI and generated applications strictly require Node.js version 18 or greater. Running on older Node.js versions will result in errors.
Fix: Ensure your development environment and deployment targets use Node.js `v18` or newer. Upgrade Node.js if necessary.
gotcha The Lowdefy CLI explicitly recommends and often requires `pnpm` for package management within projects. Using `npm` or `yarn` might lead to unexpected issues or build failures.
Fix: Install `pnpm` globally (`npm install -g pnpm`) and use `pnpm install` for project dependencies. Enable Corepack (`corepack enable`) for easier `pnpm` management.

Install

npm install lowdefy npm
yarn add lowdefy yarn
pnpm add lowdefy pnpm

Imports

Initial project setup
wrong:
```
npm install lowdefy -g
lowdefy init my-app
```
correct:
```
npx lowdefy@latest init my-app
cd my-app
pnpm install
```
The `lowdefy` package is primarily a CLI. It's recommended to use `npx` for initialization to ensure the latest version and avoid global installs. `pnpm` is the recommended package manager.
Start development server
wrong:
```
node node_modules/lowdefy/dist/index.js dev
```
correct:
```
npx lowdefy@latest dev
```
Use `npx` to run the development server within a project, or `lowdefy dev` if installed globally.
Programmatic API
wrong:
```
import { buildApp } from 'lowdefy'; // Incorrect - use Lowdefy CLI for builds
const app = require('lowdefy'); // Incorrect - not a library for direct programmatic use
```
correct:
```
// The 'lowdefy' package primarily provides a CLI and does not expose a direct programmatic JavaScript API for application logic.
```
The `lowdefy` package is designed as a CLI tool. For programmatic interactions with Lowdefy components, operators, or utilities, one typically uses specific `@lowdefy/*` packages (e.g., `@lowdefy/build`, `@lowdefy/operators`) rather than the main `lowdefy` CLI package directly.

Quickstart

This quickstart demonstrates how to initialize a new Lowdefy project, install its dependencies, and launch the local development server. It includes an example `lowdefy.yaml` to show basic page and block configuration, illustrating how to display text and link to external resources.

mkdir my-lowdefy-app
cd my-lowdefy-app

# Initialize a new Lowdefy project. This will create basic configuration files.
npx lowdefy@latest init

# Install project dependencies using pnpm (recommended by Lowdefy)
pnpm install

# Start the development server. The application will be accessible at http://localhost:3000
npx lowdefy@latest dev

# Example of a simple lowdefy.yaml configuration (add this to lowdefy.yaml after init):
# lowdefy: 5.0.0
# name: My First Lowdefy App
# pages:
#   - id: home
#     type: PageHeader
#     properties: { title: 'Welcome to Lowdefy!' }
#     blocks:
#       - id: content_card
#         type: Card
#         properties: { title: 'Hello World' }
#         blocks:
#           - id: welcome_text
#             type: Paragraph
#             properties: { content: 'This is a basic Lowdefy application. Edit lowdefy.yaml to get started!' }
#           - id: docs_button
#             type: Button
#             properties: { title: 'Go to Docs', size: 'large', type: 'primary' }
#             events:
#               onClick:
#                 - id: open_docs
#                   type: Link
#                   properties: { url: 'https://docs.lowdefy.com', target: '_blank' }

view raw JSON →