Skip to content

Getting Started with Ushka

This guide will walk you through creating your first Ushka application.

1. Create a New Project

Ushka comes with a handy CLI for scaffolding new projects. Open your terminal and run:

ushka new my_awesome_app

This will create a new directory called my_awesome_app with the following structure:

my_awesome_app/
├── ushka.toml
├── apps/
│   └── home/
│       └── views.py
└── templates/
    └── index.html

Understanding the Structure

  • ushka.toml: The main configuration file for your project. You can configure your app, server, database, and other features here.
  • apps/: This directory holds your application modules. Ushka is designed to be modular, and each subdirectory here is a separate "app".
  • apps/home/views.py: This is where you define your route handlers (the functions that respond to web requests).
  • templates/: This is where you store your Jinja2 templates for rendering HTML.

2. Start the Development Server

Navigate into your new project directory and start the development server:

cd my_awesome_app
ushka dev

You'll see output indicating that the server is running, typically on http://127.0.0.1:8000.

Ushka Dev Server

The development server features auto-reloading, so any changes you make to your code will automatically restart the server.

3. Create Your First Route

Let's modify the default home page to return a JSON response. Open apps/home/views.py. You'll see a function like this:

from ushka.http import Request
from ushka.contrib.templating import render

async def get_index(request: Request):
    return render("index.html", {"message": "Hello from Ushka!"})

Ushka uses a convention-based routing system based on function names. The name get_index is automatically mapped to GET /.

Let's change it to return JSON. You can return a dictionary directly from a view function, and Ushka will automatically serialize it to JSON and set the correct Content-Type header.

Modify the file apps/home/views.py:

from ushka.http import Request

async def get_index(request: Request):
    return {"message": "Hello, Ushka!", "status": "awesome"}

Save the file. The server will reload. Now, if you visit http://127.0.0.1:8000 in your browser or use a tool like curl, you will see the JSON response:

{
  "message": "Hello, Ushka!",
  "status": "awesome"
}

4. Render a Template

Let's go back to rendering an HTML template. Restore the original content of apps/home/views.py:

from ushka.http import Request
from ushka.contrib.templating import render

async def get_index(request: Request):
    return render("index.html", {"message": "Hello from your first Ushka template!"})

The render() function doesn't actually render the template itself. It returns a TemplateIntent object that the framework will process. This allows Ushka to inject global context into your templates automatically.

The template templates/index.html looks like this:

<!DOCTYPE html>
<html>
<head><title>{{ app_name }}</title></head>
<body><h1>{{ message }}</h1></body>
</html>

The message variable comes from the context dictionary we passed to render(). The app_name variable is a global variable provided by the framework, which it gets from your ushka.toml.

That's it! You've created a new Ushka project, started the dev server, and created your first API and HTML routes.

Next, you might want to learn more about Routing.