# Examples (/apps/examples)

The examples are not on GitHub yet. Until they are, every page that uses them shows their code in full.

## Start here [#start-here]

| Example                                       | What it shows                                                                                                 | Read with                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Parcel helper** (`examples/native-widgets`) | Two native admin panels, on orders and products, that call the app's server through signed actions. No OAuth. | [Manifest](/apps/manifest), [Signed actions](/apps/auth#signed-actions) |
| **Catalog glance** (`examples/hosted-app`)    | The `/connect` route, a hosted admin page, session tokens, App API calls and token refresh                    | [Authentication](/apps/auth)                                            |
| **USP strip** (`examples/theme-section`)      | A theme section with child blocks, a starting preset and Hungarian labels                                     | [Build a theme section](/themes/build-a-section)                        |

Each one has a README with its files, the environment variables it reads and the commands to run it. None of
them holds a secret: keys, ids and addresses come from the environment.

## The complete example [#the-complete-example]

**Recommendations by Poltura Labs** (`packages/app-sdk/examples/complete-app`) uses most of the platform at
once: five native workers in the admin and on the storefront, admin and storefront pages, actions, webhooks,
app storage, the connection routes and a session check, with tests. The [example app walkthrough](/apps/tutorial) goes through it
file by file.

## Run them [#run-them]

You need Node.js 22 or later and the `@poltura` packages, which are not on npm yet (Not published to npm yet.). Then, in an
example:

| Command                                                       | What it does                                            |
| ------------------------------------------------------------- | ------------------------------------------------------- |
| `npm run build`                                               | Bundles the workers and writes the release into `dist/` |
| `npm run validate`                                            | Checks the release the way the review queue does        |
| `npm start`                                                   | Starts the example's server on port 8787                |
| `npx poltura app publish --api "$POLTURA_API" --app <app id>` | Publishes a release for review                          |

The CLI's test suite builds both app examples and runs their servers against a stand-in for Poltura, so they
keep working as the platform changes. The theme section passes `poltura theme check` on the default theme.

To start a new app instead, `poltura app create my-app` writes a native project and `--template hosted` adds a
server with the connection routes. See [Build your first app](/apps/build-your-first-app).

## Next [#next]

- [Ship to merchants](/apps/ship): from a working example to an installed app.
- [CLI](/apps/cli): every command and option.