Build Shopify integrations in Rust with background flows, configurable service providers, and an admin rendered by the server.
This is the Rust implementation of OpenShop. It keeps the same model, HTTP API, database schema and admin screens as the TypeScript framework, compiled into a single binary: the server, the worker, the scheduler and the admin, whose pages the server renders.
This implementation is a v0 in development and has no users yet. APIs,
generated files, and workflows change without a transition period before 1.0.
You need Rust 1.94+, PostgreSQL 17, the Shopify CLI, and access to a development store.
cargo install --locked openshop-cli --version 0.1.0-rc.6
openshop init my-app # asks for a template: minimal, custom or public
cd my-app
docker compose up -d --wait
cp .env.example .env
openshop devA release candidate is installed only when its version is named. The project
depends on openshop of the CLI's version, from crates.io. To follow a commit,
tag or branch of the repository, or a local checkout, pass
--openshop-rev=<commit>, --openshop-tag=<tag>, --openshop-branch=<name>
or --openshop-path=<dir> to openshop init. The CLI of main, before a
release, installs from the repository
(cargo install --locked --git https://github.com/0xtlt/openshop-rust openshop-cli),
and its projects depend on the commit it was built from.
openshop dev pushes the database schema, then serves the API, the admin UI,
a worker and the cron scheduler on http://localhost:3000. It restarts when
sources change, and the admin UI reloads by itself. Run it through
shopify app dev to open the app in a store.
To work without a development store, run the app against a simulator of
Shopify such as local-storefront:
its ShopifyEndpoints send the Admin API and OAuth there, and make the admin
UI load the simulator's App Bridge and Polaris. A proxy or an API of your own
works the same way. See
Custom Shopify endpoints.
use openshop::prelude::*;
use serde::{Deserialize, Serialize};
/// The input of a run: it is validated, and the admin builds its form from it.
#[input]
struct SyncInput {
#[schemars(range(min = 1))]
limit: u32,
}
#[derive(Serialize, Deserialize)]
struct Order {
id: String,
name: String,
}
/// A provider is a struct: its fields are the form a merchant fills per shop…
#[derive(ProviderConfig)]
struct Warehouse {
#[field(label = "API URL", url)]
api_url: String,
#[field(label = "API Key", password, non_empty)]
api_key: String,
}
/// …and its public methods are what flows can call, with that configuration as `self`.
/// The provider is named `warehouse`, after the struct.
#[provider]
impl Warehouse {
pub async fn push(&self, orders: Vec<Order>) -> Result<usize> {
// call the service at `self.api_url` with `self.api_key`
Ok(orders.len())
}
}
/// A flow is an `async` function; its second argument is the validated input of a run.
#[flow("syncOrders")]
async fn sync_orders(ctx: FlowContext, input: SyncInput) -> Result<()> {
// Each step is checkpointed: a retried run reuses its stored output.
let orders: Vec<Order> = ctx
.step
.run("fetch-orders", async || {
// Checked against Shopify's schema when the crate compiles; `data` is typed.
let data = ctx
.shopify
.execute(graphql!(
"query($first: Int!) { orders(first: $first) { nodes { id name } } }",
first = input.limit
))
.await?;
let orders = data.orders.nodes.into_iter();
Ok(orders.map(|order| Order { id: order.id, name: order.name }).collect())
})
.await?;
ctx.step
.run("send-to-warehouse", async || {
// Checked by the compiler: a `Vec<Order>` in, a `usize` out.
Warehouse::on(&ctx.connectors).push(&orders).await?;
Ok(())
})
.await
}
/// The application is a value that lists its building blocks.
static APP: App = app! {
providers: [Warehouse],
flows: [sync_orders],
};
fn main() -> Result<()> {
APP.main()
}The binary understands dev, start, worker [--concurrency=N] and
migrate [generate|check|status].
- Providers define external API methods and credential fields. OpenShop builds a configuration form for each shop and supplies configured connectors at runtime.
- Flows define background work in named steps. OpenShop queues runs, stores checkpoints, applies retry policies, and exposes execution logs.
- App configuration lists the flows, providers, webhooks, app proxies, public routes, Shopify Functions and MCP capabilities of the application, each declared where it is written, and sets its schedules. Shopify OAuth and the embedded admin are handled by the framework.
- Shopify is reached through
shopify_api:ctx.shopifyruns its operations, checked against Shopify's schema at compile time, with the token of the installation, and its verification of session tokens, launches, app proxies and webhooks guards the routes. - The admin shows a shop its flows, runs, logs and providers, or only the
pages you wrote for it. An optional dashboard under
/ops, behind a password, shows the operator every shop. - Sentry receives the runs that fail, the handlers that fail and the panics, each with its flow and its shop, once the application gives a DSN.
In production, a web process (start) accepts requests and queues work; separate
workers (worker) execute it. PostgreSQL stores installations, credentials, runs,
and checkpoints. See Architecture and
Deploy to production.
The runtime behavior is the same; the way an application is assembled follows Rust conventions.
| TypeScript | Rust |
|---|---|
defineOpenShop({ providers }).defineConfig({ … }) |
app! { providers: […], flows: […], … }, a value of type App |
defineFlow({ name, input: type({…}), run }) |
#[flow("name")] on an async fn(ctx, input), the input being a type marked #[input] |
await step('name', fn) / step.sleep |
ctx.step.run("name", async || { … }).await? / ctx.step.sleep |
defineProvider({ fields, methods }) |
a struct with #[derive(ProviderConfig)] and #[provider] on its impl block |
connectors.warehouse.push(data) |
Warehouse::on(&ctx.connectors).push(&data), or by name with ctx.connectors.call("warehouse", "push", data) |
proxy/*.ts, routes/*.ts, admin/pages/** discovered from files |
#[proxy(GET, "/path")], #[route(GET, "/path")] and #[admin_page("/path")] on the code, listed in app! |
| A Liquid proxy that returns its template as a string | A .liquid file next to the handler, with the values of the server assigned to it: liquid!("reviews.liquid").assign("name", value) |
validate: type('string.url') |
url, non_empty, range(…) or length(…) in the #[field(…)] of a field, and validate = <validator> for anything else |
openshop.config.ts loaded by the openshop CLI |
your own binary running the application it declares: APP.main() |
defineModel('reviews', { … }) and Drizzle queries |
#[derive(Model)] on a struct, with typed rows: Review::of(&ctx).filter(Review::RATING.gte(4)) |
drizzle-kit migrations in ./drizzle |
SQL migrations in ./migrations, generated from what changed in the models (migrate generate / migrate) |
| Preact admin UI built with Vite | admin pages the server renders with Polaris web components, and one small script: no bundle to build |
createTestContext() from openshop/test |
#[openshop::test(APP)] on an async fn(ctx: &TestContext) (feature testing) |
shopify.graphql(\#graphql …`)` typed by codegen |
ctx.shopify.execute(graphql!("…", var = value)), checked and typed at compile time |
| ESLint preset | not needed |
The database tables, the encryption format of stored credentials and tokens, the MCP token format and every HTTP route are identical, so both runtimes can serve the same database. A few behaviors are intentionally stricter or more robust; they are listed in Differences.
| Path | Contents |
|---|---|
crates/openshop |
The framework: engine, server, admin pages, MCP, testing harness |
crates/openshop-macros |
The macros: app!, and the attributes and derives that declare building blocks |
crates/openshop-cli |
The openshop command: init, init-ui, dev and build |
templates/minimal |
The template of openshop init --template=minimal: one provider and one flow |
templates/custom |
The template of a custom app: every building block, with the built-in admin open to the merchant and a custom admin page |
templates/public |
The template of a public app: an admin made of its own pages for the merchants, the operator dashboard for whoever runs it |
templates/shared |
The files every project gets: Dockerfile, Procfile, Docker Compose, .env.example |
apps/preview |
What serves the custom or public template in a browser without a Shopify store |
docs |
Documentation (mdBook) |
See CONTRIBUTING.md for development and checks.
OpenShop is licensed under the MIT License.
Read the LICENSE file for the full terms.