Getting Started

The fastest way to get started with a Ludic project is to use the Cookiecutter template. Follow the steps below to set up your project quickly.

Installation Steps

Install UV Package Manager
If you don't have UV installed yet, check the official installation instructions.
Generate a Ludic Project
Use the Cookiecutter template to create a new Ludic project. Run the following command in your terminal:
```
uvx cookiecutter gh:getludic/template
```
Install Dependencies
Navigate to the new project's directory and install the required dependencies using UV:
```
uv sync --python 3.13
```
Run the Project
Start your project using Uvicorn with the following command:
```
uv run uvicorn src.main:app --reload
```
Access the Application
Open your browser and visit http://localhost:8000 to see your running application.

Structure

The cookiecutter template generates a somewhat opinionated project structure. Feel free to adjust it or suggest a different one on GitHub. Here is the structure:

 1   .
 2   ├── src
 3   │    ├── __init__.py
 4   │    ├── endpoints
 5   │    │       ├── __init__.py
 6   |    |       ├── errors.py
 7   │    │       ├── index.py
 8   │    │       └── ...
 9   │    ├── components.py
10   │    ├── main.py
11   │    ├── pages.py
12   │    └── ...
13   ├── static
14   ├── tests
15   ├── README.md
16   └── pyproject.toml

For larger applications, the structure can vary significantly. Additionally, many modules are missing, such as models and database connections. However, if you're just beginning, this still serves as a good starting point.

`pages.py`

The idea is to create a few pages (regular components) that render as valid HTML documents using the <html> root tag.

`endpoints`

The endpoints module contains all the application's endpoints. The index module includes endpoints that render when users open the site, serving as the root of your web application. The errors module contains error handlers, such as displaying the 404 page.

`components.py`

Any component you want to use in your application should be registered here. For example, a Navigation component and its attributes could be registered in the components.py file.

`main.py`

The module instantiates the LudicApp class and registers routes by importing the endpoints module.

What's Next?

In the following sections of this documentation, you will learn more about writing components and endpoints, as well as the various other tools available. You will also learn about the Catalog, which can be used to quickly create the basic layout of your web application.