# Copyright 2020-2021 Lowdefy, Inc # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # http://www.apache.org/licenses/LICENSE-2.0 # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. _ref: path: templates/general.yaml.njk vars: pageId: cli pageTitle: The CLI section: Concepts filePath: concepts/cli.yaml content: - id: md1 type: MarkdownWithCode properties: content: | The Lowdefy CLI is used to develop a Lowdefy app locally, and to build Lowdefy apps for deployment. We recommend running the CLI using `npx`, to always use the latest version: ``` npx lowdefy@latest ``` or, to use a specific version: ``` npx lowdefy@version ``` Alternative, you can install the CLI globally or to a npm project (with a `package.json` file) via npm or yarn. To install the CLI globally run: ``` npm install lowdefy -g ``` The CLI can then be run using `lowdefy` as the executable name: ``` lowdefy ``` # CLI commands ## build The `build` command runs a Lowdefy build. The options are: - `--base-directory `: Change base directory. The default is the current working directory. - `--blocks-server-url `: The URL from where Lowdefy blocks will be served. See below for more information. - `--disable-telemetry`: Disable telemetry. - `--output-directory `: Change the directory to which build artifacts are saved. The default is `/.lowdefy/build`. - `--ref-resolver `: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver. ## build-netlify The `build-netlify` command creates a production build for the [Netlify](https://www.netlify.com) web hosting service. It is designed to run as the Netlify build command. We recommend setting the build command to `npx lowdefy@latest build-netlify`. The Netlify publish directory should be set to `.lowdefy/publish`, and the functions directory set to `.lowdefy/functions`. - `--base-directory `: Change base directory. The default is the current working directory (The base directory should rather be configured in the Netlify build settings). - `--blocks-server-url `: The URL from where Lowdefy blocks will be served. See below for more information. - `--disable-telemetry`: Disable telemetry. - `--ref-resolver `: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver. ## clean-cache The Lowdefy CLI caches block metadata, and build and server scripts in the `.lowdefy/cache` directory. These cached files can be removed using the `clean-cache` command. - `--base-directory `: Change base directory. The default is the current working directory. - `--disable-telemetry`: Disable telemetry. ## dev The `dev` command starts a Lowdefy development server, running locally. It can be accessed in a browser at [http://localhost:3000](http://localhost:3000). The CLI watches the file system, and rebuilds the app and reloads served pages every time a change is made to any of the files in the project directory. - `--base-directory `: Change base directory. The default is the current working directory. - `--blocks-server-url `: The URL from where Lowdefy blocks will be served. See below for more information. - `--disable-telemetry`: Disable telemetry. - `--port `: Change the port the server is hosted at. The default is `3000`. - `--ref-resolver `: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver. - `--watch `: A list of paths to files or directories that should be watched for changes. - `--watch-ignore `: A list of paths to files or directories that should be ignored by the file watcher. Globs are supported. #### Examples Run the dev server, watching a relative directory for file changes: ```txt npx lowdefy@latest dev --watch ../other-project ``` Run the dev server, ignoring the public directory: ```txt npx lowdefy@latest dev --watch-ignore public/** ``` # Configuration All the CLI options can either be set as command line options, or the `cli` config object in your `lowdefy.yaml` file. Options set as command line options take precedence over options set in the `lowdefy.yaml` file. The config in the `lowdefy.yaml` cannot be referenced using the `_ref` operator, but need to be set in the file itself. Options set in the `lowdefy.yaml` should be defined in camelCase. The options that can be set are: - `blocksServerUrl: string`: The URL from where Lowdefy blocks will be served. See below for more information. - `disableTelemetry: boolean`: Disable telemetry. - `outputDirectory: string`: Change the directory to which build artifacts are saved. The default is `/.lowdefy/build`. - `refResolver: string`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver. - `port: number`: Change the port the server is hosted at. The default is `3000`. - `watch: string[]`: A list of paths to files or directories that should be watched for changes. - `watchIgnore: string[]`: A list of paths to files or directories that should be ignored by the file watcher. Globs are supported. The `--base-directory` option cannot be set from the `lowdefy.yaml` file. # Telemetry The CLI collects usage and error information to help us fix bugs, prioritize features, and understand how Lowdefy is being used. All telemetry can be disabled by setting the `disableTelemetry` flag in `cli` config object in your `lowdefy.yaml` file (this cannot be a reference to another file), or by using the `--disable-telemetry` command line flag.: ###### `lowdefy.yaml` ```yaml lowdefy: LOWDEFY_VERSION cli: disableTelemetry: true ``` We collect the following information: - The CLI version. - The Lowdefy version of your app. - A random local app id (stored locally in your project folder at `.lowdefy/cli.json`). - The CLI command used. - If the CLI is being used in the Netlify CI environment (when using the `build-netlify` command). - Your IP address. - Error messages and stack traces for any errors. # Blocks Server The Lowdefy default blocks are not included in the Lowdefy build output, but are served from a CDN, and imported into the app using webpack module federation. All the default Lowdefy blocks are hosted at: ```yaml https://blocks-cdn.lowdefy.com/v{LOWDEFY_VERSION}/ ``` If you wish to host your own blocks instead, this url can be configured using the `--blocks-server-url` CLI option. This URL should serve the build artifacts of the Lowdefy default block packages (located in the `dist` directory). Each blocks package should be served under a path that corresponds to the package name. For example, `@lowdefy/blocks-basic` should be served under `{BLOCK_SERVER_URL}/blocks-basic/`. The required blocks packages and server paths are: - `@lowdefy/blocks-basic` to be hosted at `{BLOCK_SERVER_URL}/blocks-basic/`. - `@lowdefy/blocks-antd` to be hosted at `{BLOCK_SERVER_URL}/blocks-antd/`. - `@lowdefy/blocks-color-selectors` to be hosted at `{BLOCK_SERVER_URL}/blocks-color-selectors/`. - `@lowdefy/blocks-markdown` to be hosted at `{BLOCK_SERVER_URL}/blocks-markdown/`. - `@lowdefy/blocks-echarts` to be hosted at `{BLOCK_SERVER_URL}/blocks-echarts/`. If you wish to run the CLI dev server, the `@lowdefy/renderer` package build artifacts (located in the `dist` directory) should also be served from `{BLOCK_SERVER_URL}/renderer/`. - _ref: path: templates/navigation_buttons.yaml vars: previous_page_title: Overview previous_page_id: overview next_page_title: Lowdefy App Schema next_page_id: lowdefy-schema