Build apps and themes for Hekana: where developers start

Hekana has a developer site at hekana.dev. It documents the two things an outside developer can build for a Hekana store: themes, which change how a store looks, and apps, which change what a store does. This post is a map: which one you need, the first steps for each, and what is not available yet, so you do not spend a day on something that is not built.

Both are in early access. The developer docs mark exactly what works and what does not, and this post repeats that rather than smoothing it over.

Theme or app?

A store can use a theme and install apps, and neither needs the other.

| | Theme | App | | --- | --- | --- | | It changes | How the store looks and is laid out | What the store does: behaviour, data, integrations | | You write | Sneferu: HTML with hk-* tags, a theme.json and CSS | Code on your own server that calls the Apps API | | It reaches a store | The merchant installs a published theme | The store owner approves your app's consent screen | | Can it run code | No, a theme cannot run JavaScript | Yes, on your server | | Start with | Build your first theme | Create your first app |

Build a theme

Sneferu is the language and SDK for Hekana store themes. A theme is a folder of HTML-like .snf templates with hk-* tags, a theme.json manifest, language files and CSS. The CLI checks it, previews it with sample data and compiles it to one JSON artifact that Hekana renders.

You need Node.js 20 or newer. Then:

npx sneferu init my-theme
cd my-theme
npx sneferu dev

init copies a starter theme. You can start from a finished example instead: starter is a neutral complete store, and there are gaming and digital-product designs such as arcade, console, esports, creator, license and bento. dev opens a local preview with sample data.

Three rules shape everything you write. A theme uses only the documented hk-* tags, it cannot run JavaScript, and it has no raw form inputs except through the documented search and cart tags.

To publish, sign in with npx sneferu login or a developer key from hekana.dev/account. You get a free dev store with sample products to test on. It takes no orders, accepts no payments and search engines are told not to index it. Themes from outside developers are reviewed by Hekana before merchants can use them.

Read the theme guide from the start. If you only want a store with a ready-made look, you do not need any of this: see how to build your store with Hekana and the theme gallery.

Build an app

A Hekana app is a program that runs outside Hekana and acts on one store through the Apps API, after the store owner has approved it. It can read orders, products and customers, place orders, make discount codes, message customers, keep its own small data store, offer a checkbox at checkout and listen to store events.

The path is:

1. Register the app and list the scopes it needs. It starts as a draft.
2. Submit it. A Hekana reviewer approves it, sends it back with a reason, or suspends it.
3. Once approved, a store owner opens your consent link, sees the scopes and approves.
4. Your server exchanges the code for tokens, calls the Apps API and receives webhooks.
5. The store owner can uninstall at any time.

Every token belongs to one installation, so every request is about exactly one store. An app cannot name another store.

Start at the apps overview, then the getting started page.

What is not available yet

The docs list these, and they are worth knowing before you plan:

• The SDK packages are not published to npm. @hekana/apps-sdk, hekana-sdk and create-hekana-app cannot be installed yet. You call the Apps API over HTTP. The Sneferu CLI (sneferu) is on npm.
• There is no test mode for apps. The consent flow only runs for approved apps.
• Third-party apps cannot use Hekana's subscription plans, trials or one-time purchases. Those exist for Hekana's own apps.
• There are no custom theme blocks for third-party apps. The list of blocks is closed.
• An app cannot add checkout fees or change prices. A checkout extension can only offer one of the store's own products.

What merchants see

Merchants install Hekana's own apps from the Apps page in their dashboard. See how to install, turn on and manage Hekana apps for that side of it.

Questions

Do I need to be a Hekana merchant to develop? You need a Hekana account to sign in at hekana.dev. A free dev store is created for you for theme testing.

Can I sell my theme or app? The developer docs do not describe selling themes. For apps, third-party plans and purchases are not available yet.

Is the Apps API stable? It exists, is tested and is versioned with a Hekana-Api-Version header, but it is early access. Check the status note on the apps overview before you commit.

Where do I ask for something that is missing? Contact us.

New to Hekana? See the plans and start free.