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 will write the ticket data to Google Sheets, and we will deploy the app using Netlify.

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 12 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.

Step 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

Step 1.2 - Open a command line interface

Open your computer's command line interface (Windows CMD, Terminal on MacOS), and change directory (cd) to the project directory.

Step 1.3 - Initialize an app

Use the Lowdefy CLI to initialize your project.

Run the following in your terminal:

npx lowdefy@latest init

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.

We recommend using npx to run the Lowdefy CLI, since this ensures your are always running the latest version. You can also install the CLI globally or locally using npm install lowdefy

To paste into the Windows Command Prompt, you can right-click and select paste.

A "lowdefy.yaml" file already existsIf you get a 'A "lowdefy.yaml" file already exists' error, delete the "lowdefy.yaml" file in your current working directory or run the command in a new directory.

Step 1.4 - Start the development server.

Run:

npx lowdefy@latest dev

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

Welcome to your Lowdefy app

We are excited to see what you are going to build

Could not find "lowdefy.yaml"If you get a 'Could not find "lowdefy.yaml"' error, make sure your current working directory contains the "lowdefy.yaml" file. You can verify this by running the "dir" (Windows) or "ls" (MacOS) command.

Step 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: 3.12.6
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: HeartTwoTone
                    color: '#f00'
                areas:
                  extra:
                    blocks:
                      - id: docs_button
                        type: Button
                        properties:
                          size: large
                          title: Let's build something
                          color: '#1890ff'
                        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.

Step 1.6 - Make some changes

Change some of the text in the app. Change the text Welcome to your Lowdefy app to Hello __YOUR_NAME_HERE__ (filling in your own name). Save the file and browser should automatically refresh, and you should see your changes.

YAML Files

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. If you don't have any experience using YAML, this video is a good introduction.

What happened

The Lowdefy CLI helps you develop a Lowdefy app.

We used the npx lowdefy@latest init command to initialize a new project. This created all the essential files.

We also used the npx lowdefy@latest dev command to start a development server. The development server runs a Lowdefy app locally on your computer, which can be accessed at http://localhost:3000. The development server watches your configuration files, and if any of them changes it "builds" (compiles the configuration together for the server to serve) the configuration again and refreshes the browser to show the changes.