Local Development

This page will walk you through the installation of Dara framework and the creation of a simple 'Hello World' app.

Requirements

There are two prerequisites to being able to use the Dara framework:

• Python v3.8+
• NodeJS v14+ (Don't worry you don't need to understand any JS, this is used to build the application in production mode)

You can install both of these via the Homebrew package manager on MacOS or follow the instructions on their websites: Python node.

Once you have these tools installed the best way is to create a Python virtual environment or start a new Python Poetry project so that our dependencies don't conflict with anything you have installed on your wider system.

Installation - Starting a new project

There are two methods in which you can start a new Dara project:

• The first is through using the CLI for creating apps.
• The second is by manually starting a project with poetry or pip.

CLI Quickstart

The CLI can be installed globally with

pip install create-dara-app

You can also use `pipx` to install the CLI in an isolated global virtual environment

pipx installation instructions are available here but the short version is:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

You might need to restart your terminal after installing pipx. The ensurepath command adds necessary directories to your PATH, the changes might not be reflected in your terminal until you restart it.

To install the CLI globally with the pipx package, run the following command:

pipx install create-dara-app

You should see a message saying that the CLI has been installed successfully. Check that the CLI is available by running the following command:

create-dara-app --version

Poetry Quickstart

Poetry can be installed following these instructions. You can then create a new Poetry project with the following command in your project's directory:

poetry init

This command will guide you through creating your pyproject.toml config.

danger

When following the prompts, you can simply hit enter for most however when prompted for the Compatible Python versions please enter >=3.8.0, <3.12.0.

Compatible Python versions [^3.8]:  >=3.8.0, <3.12.0

This is necessary because Dara libraries support python versions >=3.8.0, <3.12.0.

The contents of the pyproject.toml will be something like the following:

[tool.poetry]
name = "<your-app-name>"
version = "0.1.0"
description = ""
readme = "README.md"
packages = [{include = "<your_app_name>"}]

[tool.poetry.dependencies]
python = ">=3.8.0, <3.12.0"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

As the readme field is set to "README.md", you will want to make sure to have a README.md file in your directory. This file can be empty to start with and you can fill it out at a later time with important information about the app. You will now have the following file structure:

- <your-app-name>/
    - pyproject.toml
    - README.md

Then create a folder in your project with the same name as the project itself. Within the folder add two empty files, one called __init__.py and the other called main.py. You will have the following file structure:

- <your-app-name>/
    - <your_app_name>/
        - __init__.py
        - main.py
    - pyproject.toml
    - README.md

danger

The folder cannot have hyphens, and therefore you must substitute - for _. For example, the first-dashboard project will have a first_dashboard subfolder.

Now that you have initiated your Poetry project, you can install it with the following:

poetry install

You are now ready to add the core of the Dara framework:

poetry add dara-core --extras all

Pip Quickstart

You can create a virtual environment with the following command:

python3 -m venv .venv

This will create a virtual environment in your current working directory. You can then activate that environment with the following command:

source .venv/bin/activate

Create another folder in your project with the same name as the project itself. Within the folder add two empty files, one called __init__.py and the other called main.py. You will have the following file structure:

- <your-app-name>/
    - <your_app_name>/
        - __init__.py
        - main.py

danger

The folder cannot have hyphens, and therefore you must substitute - for _. For example, the test-application project will have a test_application subfolder.

Now in order to install the project in editable mode you need a pyproject.toml file with the following contents at the minimum:

<your-app-name>/pyproject.toml

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "<your_app_name>"
version = "0.1.0"
requires-python = ">=3.8, <3.12.0"

[tool.setuptools]
packages = ["your_app_name"]

You can now install the project in editable mode with the following command:

pip install -e .

caution

In order to use the PEP 660 pyproject.toml-based editable installation process, you need the following dependencies:

• pip >= 21.3
• setuptools >= 64.0.0

Those can be upgraded with:

python -m pip install --upgrade pip
pip install --user --upgrade setuptools

Alternatively you can use a setup.py or setup.cfg file instead of the pyproject.toml. You can read more about the setup in the setuptools documentation.

You are now ready to install the core of the Dara framework:

pip install dara-core[all]

Building your app

The following will go through two examples of building a simple app - one using the create-dara-app command line interface and the other using Poetry manually.

CLI Quickstart

If you have installed the create-dara-app package, you can follow these instructions.

create-dara-app creates an app with two pages. The first page is an introductory page with a welcome message, and the second page is a gallery of components, providing a simple example of how to use each component offered in dara-components.

- <your-app-name>/
    - <your_app_name>/
        - pages/
            - intro_page.py
            - components_page.py
        - utils/
            - components.py
            - template.py
        - main.py
    - pyproject.toml
    - README.md

To create this app run the following command:

create-dara-app

note

By default the CLI will attempt to scaffold your project with poetry but will fall back to pip if poetry is not present. This can be overriden with --packaging pip or --packaging poetry flag.

Manual Quickstart

If you have set up your project manually with Poetry or pip, you will have the following file structure:

- <your-app-name>/
    - <your_app_name>/
        - __init__.py
        - main.py
    - pyproject.toml
    - README.md

Now you can start coding your app. In main.py, copy the following contents into it:

<your-app-name>/<your_app_name>/main.py

from dara.core import ConfigurationBuilder
from dara.components import Heading

# Here you initialize the app config, which uses a Builder pattern to
# build up the app piece by piece.
config = ConfigurationBuilder()

# Here you add a single page to the application, with a title of 'Hello World'
# and the text 'Hello World!' on the page.
config.add_page('Hello World', Heading('Hello World!'))

note

Dara expects configuration to be available as a config variable in {root_package}/main.py by default.

As an example, in a project called test-application your code should be in (...)/test-application/test_application/main.py. Take note of the dash being replaced by an underscore in the package name.

The default behavior can be overridden using the --config CLI flag which takes the format of --config {root_package}.{module}:{variable}.

Running your application

Once you've got your project setup, you will want to run the application so you can see your application in action. This can be done with a single command from the root of your project:

Poetry

To start the app:

poetry run dara start --reload

Pip

Within the virtual environment created earlier then:

dara start --reload

note

You need to activate the virtual environment before running the command. If you have not activated the virtual environment, you might see an error saying that the dara command cannot be found. To activate the virtual environment, e.g. on Linux/MacOS run the following command:

source .venv/bin/activate

You can read more about virtual environments on the venv package documentation site.

tip

The --reload flag here will cause it to automatically reload the backend and UI whenever any changes are made and saved.

By default it will infer and watch the parent directory of the module containing your config variable. This can be overriden using the --reload-dir flag which can be used multiple times to watch multiple specified directories instead of the default one.

# Example structure
- decision-app/
    - decision_app/
        - main.py
        - pages/
        - utils/
    - pyproject.toml

# Will watch for changes in these directories: ['(...)/decision-app/decision_app']
dara start --reload
# Will watch for changes in these directories: ['(...)/decision-app/decision_app/pages']
dara start --reload-dir decision_app/pages
# Will watch for changes in these directories: ['(...)/decision-app/decision_app/utils', '(...)/decision-app/decision_app/pages']
dara start --reload-dir decision_app/pages --reload-dir decision_app/utils

This command will start a local development server and will start your application at http://localhost:8000.

If you have used the create-dara-app CLI, your app will look like the following:

If you have set up your app manually, your app will look like the following: