# Your first application

Create a project, add an app, and serve its first route. You need Go 1.26.10+.
The standard project includes accounts and requires PostgreSQL 18 for runtime commands.

## Ask your agent

Copy this prompt into your coding agent. Change `myapp` and the module path for your project.

```text
Read https://cicadel.fauzaanu.com/en/dev/llms.txt and its quick-start guide.
Create a Cicadel application in ./myapp with module example.com/myapp.
Use the dev version and record the resolved Go dependency versions.
Add a local notes app, register it in project/apps.go, and serve GET /notes/.
Configure PostgreSQL for the standard account and migration workflow. Do not overwrite an existing project.
Run the application checks and tests, start it locally, and verify /notes/ over HTTP.
Tell me the URL, files changed, and checks that passed.
```

For another version, use the [agent setup page](https://cicadel.fauzaanu.com/en/dev/intro/ai/index.md). Its links and prompts follow the documentation version selector.

## Create the project yourself

Run these commands from the directory that will contain `myapp`:

```sh
export GOPRIVATE=github.com/fauzaanu/cicadel
go run github.com/fauzaanu/cicadel/cmd/cicadel@main startproject myapp example.com/myapp
cd myapp
go get github.com/fauzaanu/cicadel@main
go mod tidy
export DATABASE_URL='postgres://USER:PASSWORD@localhost/myapp?sslmode=disable'
export CICADEL_DEBUG=true
export CICADEL_SECURE_COOKIES=false
go run manage.go migrate
go run manage.go check
go run manage.go runserver
```

Open `http://127.0.0.1:8000`. Stop the server with Ctrl-C before continuing.
The repository currently requires authorized GitHub access. Configure Git authentication and `GOPRIVATE=github.com/fauzaanu/cicadel` for direct module access. There are no tagged releases yet, so `@main` selects the development branch. Commit `go.mod` and `go.sum` to keep the resolved version. Inside the project, `go tool cicadel` uses that project's CLI.

## Add and register an app

From `myapp`, create a notes app:

```sh
go tool cicadel startapp notes
```

Add the app to `project/apps.go`, retaining the core registrations:

<!-- example: quickstart/project/apps.go -->
```go
package project

import (
    "example.com/myapp/apps/notes"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/contrib/formsets"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        formsets.App(),
        notes.New(),
    }, nil
}
```

Change `example.com/myapp` if you chose a different module path. Creating a folder or importing a package does not register an app; this list does.

## Check the route

The generated `apps/notes/urls.go` connects `/notes/` to `Index`:

```go
func URLs() []urls.Route {
    return urls.Include("/notes", "notes",
        urls.Path("GET", "/", "index", Index),
    )
}
```

Start the app, then fetch the route from a second terminal:

```sh
go run manage.go apps
go run manage.go check
go test -race ./...
go run manage.go runserver
```

```sh
curl http://127.0.0.1:8000/notes/
# {"app":"notes"}
```

## Make changes

| File | What to change |
| --- | --- |
| `project/apps.go` | Register local and installed apps |
| `project/settings/settings.go` | Set project defaults |
| `apps/notes/urls.go` | Add routes |
| `apps/notes/views.go` | Handle requests |
| `apps/notes/models.go` | Define database models when needed |
| `project/home.templ` | Edit the homepage |

For UI changes, install the CSS tool once, then rebuild and check:

```sh
go tool cicadel ui css install
go tool cicadel ui build
go tool cicadel ui check --json
```

Restart the server after rebuilding. For automatic rebuilds and restarts, run `go tool cicadel dev` instead of `runserver`.

## Choose your next step

- [Render a component](https://cicadel.fauzaanu.com/en/dev/howto/component-authoring/index.md).
- [Add htmx interactions](https://cicadel.fauzaanu.com/en/dev/howto/htmx/index.md).
- [Install a reusable app](https://cicadel.fauzaanu.com/en/dev/topics/installable-apps/index.md).
- [Add PostgreSQL migrations](https://cicadel.fauzaanu.com/en/dev/topics/migrations/index.md).
- [Start with sign-in screens](https://cicadel.fauzaanu.com/en/dev/topics/authentication/index.md).

When ready to deploy, build `go build -o bin/server .` and follow [deployment configuration](https://cicadel.fauzaanu.com/en/dev/howto/operations/index.md). The local debug and insecure-cookie settings above are for development only.