> For the complete documentation index, see [llms.txt](https://prehledne-navody.gitbook.io/prehledne-navody-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prehledne-navody.gitbook.io/prehledne-navody-docs/documentation/getting-started/your-first-project.md).

# Your first project

This walkthrough goes deeper than the [Quickstart](broken://pages/d8dde992c3b506ec2b54b125e6aef8f498f18ed3). By the end, you'll have a real project with environment variables, a custom build, and a preview deployment workflow.

{% hint style="info" %}
We'll use a generic web project for this tutorial. The same pattern works for static sites, APIs, and worker services.
{% endhint %}

## 1. Plan your project structure

Before clicking anything, decide how you want to organise your work:

| You have…                  | Use…                                       |
| -------------------------- | ------------------------------------------ |
| One app, one team          | A single project in your default workspace |
| Several related apps       | A workspace with one project per app       |
| Multiple unrelated clients | A separate workspace per client            |

Most people start with the middle option. You can always restructure later.

## 2. Create the project

{% stepper %}
{% step %}

#### From the workspace dashboard

Click **New project**. You'll see three creation options.

{% tabs %}
{% tab title="From a repo" %}
Connect your version control provider and select a repository. The platform detects your framework and pre-fills sensible defaults.
{% endtab %}

{% tab title="From a template" %}
Pick a starting template — blog, dashboard, API, etc. — and the platform creates a new repository for you.
{% endtab %}

{% tab title="Empty project" %}
Skip both and create an empty project. Useful when you want to wire up a custom CLI workflow.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Name and configure

Give your project a name and choose its visibility.

* **Public** — anyone with the URL can view the deployed site
* **Private** — only invited members can access it
* **Password-protected** — anyone with the URL and password can view it
  {% endstep %}

{% step %}

#### Set environment variables

If your project needs API keys, database URLs, or other secrets, add them under **Project settings → Environment**.

```bash
DATABASE_URL=postgres://...
API_TOKEN=...
```

{% hint style="warning" %}
Never commit secrets to your repository. Use environment variables for anything sensitive.
{% endhint %}
{% endstep %}
{% endstepper %}

## 3. Customise your build

The platform auto-detects most frameworks, but you can override the defaults in your project's `platform.yaml`:

```yaml
build:
  command: npm run build
  output: dist/
  node: 20
  install: npm ci

deploy:
  framework: auto
  routes:
    - source: /api/*
      destination: /api/[...path].js
```

Common overrides:

* **`build.command`** — the script that produces your output
* **`build.output`** — the folder containing your built files
* **`build.node`** — the Node.js version to use
* **`deploy.routes`** — custom routing rules

## 4. Set up preview deploys

Preview deploys give every branch and pull request its own live URL. They're enabled by default, but you can fine-tune the behaviour:

```yaml
preview:
  enabled: true
  branches:
    include: ["**"]
    exclude: ["release/*"]
  comments: true
```

When `comments: true`, the platform posts a comment on each pull request with the preview URL.

## 5. Deploy

Push to your main branch (or click **Deploy** manually). The platform will:

1. Clone your repository
2. Install dependencies
3. Run your build command
4. Upload the output
5. Promote to your live URL

{% hint style="success" %}
You'll get a notification when the build completes — by email, Slack, or whatever you configured under [Automations](/prehledne-navody-docs/documentation/guides/automations.md).
{% endhint %}

## Sample project

If you'd like to skip ahead and see a fully configured project, download our sample:

{% embed url="<https://github.com/GitbookIO/gitbook-templates>" %}

## Where to go next

Now that you have a working project, you can check out:

{% content-ref url="/pages/56a52747d54863f8df67ff3ce908938888c69b66" %}
[Custom domains](/prehledne-navody-docs/documentation/guides/custom-domains.md)
{% endcontent-ref %}

{% content-ref url="/pages/d9d593aeabc52a165190bf8c93720491a4eb9682" %}
[Automations](/prehledne-navody-docs/documentation/guides/automations.md)
{% endcontent-ref %}

{% content-ref url="/pages/fb922e107b31a3e9e9fcf81410029e993b0a9afc" %}
[Permissions](/prehledne-navody-docs/documentation/core-concepts/permissions.md)
{% endcontent-ref %}