1. Getting started

In this tutorial, we will be creating a simple ticketing app that allows users to file new tickets and see a list of outstanding tickets. The app reads product data from DummyJSON and will write the ticket data to an SQLite database.

Requirements

The Lowdefy CLI (Command Line Interface) is needed to run the development server. To run the Lowdefy CLI you need to install Node.js at version 18 or greater. If you don't have it installed, download Node.js from https://nodejs.org/en/download/, and follow the installation steps for your computer. All of the default settings given by the installer are fine for what we need. You will also need a text editor to modify the Lowdefy configuration files.

Lowdefy also requires pnpm to be installed. We recommend making activating Corepack, even though it is an experimental feature, as this is the simplest way to install pnpm. Alternative methods to install pnpm can also be found here. To activate Corepack, run the following in your computer's command line interface (Windows CMD, Terminal on MacOS).

YAML files

If you don't have any experience using YAML, please familiarize yourself YAML before continuing.

This video is a good introduction to YAML.

Lowdefy apps are written using YAML files. YAML files are useful for storing structured data, like the configuration of all of the elements of your app. YAML files focus on being easily readable by humans, this means they don't use lots of syntactic elements like brackets that make it difficult for humans to read, but instead use indentation to indicate structure. While this does make the file easier to read, this means care has to be taken that the data structure is as you intended.

Lowdefy apps can also be defined using JSON files, or a mix of YAML and JSON. We find YAML files more convenient to write.

1.1. Create a project directory

Create a directory (folder) on your computer where you would like to create the configuration files for your project. We will be referring to this directory as the project directory.

1.2. Open a command line interface

Open your computer's command line interface and change directory (cd) to the project directory.

1.3. Initialize an app

Use the Lowdefy CLI to initialize your project. We recommend using pnpx to run the Lowdefy CLI, since this will always run the latest version of the CLI.

Run the following in your terminal:

This will create two files in your current working directory. The first file, called lowdefy.yaml is the starting point of your app's configuration. The second, called .gitignore, is a hidden file that tells git, a version control tool, not to version or upload some specific files.

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.

1.4. Start the development server

Run:

Your browser should open on http://localhost:3000, and you should see the following:

Error: Could not find "lowdefy.yaml": Make sure your current working directory contains the lowdefy.yaml file. You can verify this by running the dir (Windows) or ls (MacOS) command.

1.5. Open the configuration file

Open the lowdefy.yaml file using a text editor like VS Code. The content of the file should look like this:

lowdefy: 4.4.0
name: Lowdefy starter

pages:
  - id: welcome
    type: PageHeaderMenu
    properties:
      title: Welcome
    areas:
      content:
        justify: center
        blocks:
          - id: content_card
            type: Card
            style:
              maxWidth: 800
            blocks:
              - id: content
                type: Result
                properties:
                  title: Welcome to your Lowdefy app
                  subTitle: We are excited to see what you are going to build
                  icon:
                    name: AiOutlineHeart
                    color: '#f00'
                areas:
                  extra:
                    blocks:
                      - id: docs_button
                        type: Button
                        properties:
                          size: large
                          title: Let's build something
                        events:
                          onClick:
                            - id: link_to_docs
                              type: Link
                              params:
                                url: https://docs.lowdefy.com
                                newWindow: true
      footer:
        blocks:
          - id: footer
            type: Paragraph
            properties:
              type: secondary
              content: |
                Made by a Lowdefy 🤖

This configuration completely describes the app you are running.

1.6. Make some changes

Let's modify the button to link to the Lowdefy Discord community instead of to the Lowdefy docs.

First, change Let's build something to Join Lowdefy on Discord, then save the file. Your page should automatically refresh and you should see the changed text of the button.

Next, update the link url to the Lowdefy Discord link, replace https://docs.lowdefy.com with https://discord.gg/QQY9eJ7A2D, then save the file. If you now click the button it should open a new window linking to the Lowdefy Discord Channel - Join our community to ask questions or learn more regarding Lowdefy ❤️