Create your first Project

Now that PyBlade is installed, let's create your first project and make sure everything is working correctly.

PyBlade comes with a built-in Command Line Interface (CLI) that helps you perform common development tasks. The CLI can create projects, generate templates and components, run development tools, and simplify your daily workflow.

We will explore all available PyBlade CLI commands in detail later. For now, let's use the CLI to initialize your first project.

Initialize a PyBlade project

To create a new PyBlade project, run:

pyblade init

PyBlade will guide you through the setup process and ask you a few questions:

Project name — Choose a name for your project. You can use . to initialize PyBlade directly in the current directory.
Python web framework — Select the framework your project uses. Currently, PyBlade supports Django.

After answering these questions, PyBlade will initialize your project based on the selected framework and prepare everything you need to start developing.

During this process, PyBlade creates the required project structure and adds a pyblade.toml file at the root of your project.

This file contains PyBlade's configuration and allows the engine and CLI to understand your project. You can use it later to customize PyBlade's behavior, but for now, the default configuration is all you need.

With the setup complete, you can start building your application without worrying about additional configuration.

Start the development server

Once your project has been initialized, you can start the development server with:

pyblade serve

This command starts your application and launches the development environment.

Open your browser and visit:

http://127.0.0.1:8000

If everything is configured correctly, you should see your PyBlade project running.

Create a PyBlade template

PyBlade templates are regular .html files, so you can always create them manually wherever you need them.

For example, you could simply create:

welcome.html

However, when working on a project, creating files manually can become repetitive. For convenience, PyBlade provides a dedicated CLI command for generating templates:

pyblade make:template welcome

This creates a new welcome.html template in the appropriate templates directory with the basic HTML structure.

You can also specify a path when you want to organize your templates into subdirectories:

pyblade make:template pages.welcome

This will create:

welcome.html

The CLI is designed to make common tasks like this quick and consistent. You are never required to use it, though—PyBlade templates are just HTML files, so you can create and organize them manually whenever you prefer.

We'll explore the other make: commands and the rest of the PyBlade CLI later.

Where should your templates live?

One important thing to understand is that PyBlade does not introduce a new project structure. It follows the conventions of the web framework you are using.

Whether you're working with Django, Flask, or another supported framework, your templates are organized according to that framework's standard structure. PyBlade simply integrates with the existing template system.

For example, Django gives you some flexibility: you can keep templates in a project-level templates directory, or organize them inside individual applications. Flask, on the other hand, conventionally looks for templates in a templates directory at the root of the application.

Django supports both project-level and application-level templates.

A project-level templates directory can be shared across your entire project:

welcome.html

manage.py

pyblade.toml

You can also keep templates inside an individual Django app:

urls.py

views.py

manage.py

pyblade.toml

Both approaches are supported. Choose the organization that makes the most sense for your project.

Flask conventionally looks for templates inside a templates directory at the root of your application:

welcome.html

app.py

pyblade.toml

You can organize your templates into subdirectories as your application grows.

This framework-aligned approach means you don't have to learn a completely different project structure just because you're using PyBlade. If you already know how your framework organizes templates, you already know where your PyBlade templates belong.

Now, let's open the generated welcome.html file and replace its contents with the following:

templates/welcome.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First PyBlade Template</title>
</head>
<body>
    <h1>Hello from PyBlade!</h1>
    <p>Your first PyBlade template is working.</p>
</body>
</html>

There is nothing special here yet. It is just HTML and that's exactly the point.

A PyBlade template starts as regular HTML. You can use everything you already know about HTML and gradually add PyBlade's features when you need them.

Now let's render it.

Rendering PyBlade templates

Our template is ready, but there is one last step before we can see it in the browser: we need to tell our framework, which URL should display it.

First, create a view that renders the template:

views.py

from django.shortcuts import render

def welcome_view(request):
    return render(request, "welcome")

Then, open your project's urls.py and connect the welcome/ URL to this view:

urls.py

from django.urls import path
from .views import welcome_view

urlpatterns = [
    path("welcome/", welcome_view),
]

To render welcome.html from the Django app's my_app/templates/my_app/ directory, use the template path without the .html extension and use dots to separate folders:

views.py

from django.shortcuts import render

def welcome_view(request):
    return render(request, "my_app.welcome")

This notation keeps template references short and consistent across your project.

If you prefer Django's class-based views, PyBlade works with them just as naturally. Simply set the template_name attribute using the same dot notation:

views.py

from django.views.generic import TemplateView

class WelcomeView(TemplateView):
    template_name = "my_app.welcome"

Important

For compatibility, PyBlade also supports the traditional Django template notation:

views.py

def welcome_view(request):
    return render(request, "my_app/welcome.html")

The same applies to class-based views:

views.py

class WelcomeView(TemplateView):
    template_name = "my_app/welcome.html"

Both formats work, but the dot notation is the recommended approach for PyBlade projects.

Open your app's routes.py and connect the /welcome URL to this view:

routes.py

from flask import Flask
from pyblade.flask import render

app = Flask(__name__)

@app.route("/welcome")
def welcome():
    return render("welcome")

Start your development server if it is not already running:

pyblade serve

Now open the following address in your browser:

http://127.0.0.1:8000/welcome/

You should see your first PyBlade page. And that's it. You've just created and rendered your first PyBlade template.

So far, there is nothing particularly magical happening: Your framework handles the request, PyBlade processes the template, and the resulting HTML is sent to the browser.

What's next?

Congratulations! You have created your first PyBlade project and successfully prepared your development environment.

Now it is time to discover what makes PyBlade unique: its expressive template system.

In the next sections, you will learn how to:

Display dynamic data inside your templates.
Use PyBlade directives such as @if, @for, and @include.
Create reusable components.
Organize your pages with layouts and template inheritance.
Build interactive interfaces with Live Components.

Let's explore the core of PyBlade.

Create your first Project

Initialize a PyBlade project

Start the development server

Create a PyBlade template

Where should your templates live?

Rendering PyBlade templates

What's next?

On this page