RFC - vision of app-template and app-sdk

[lkostrowski]

Context

app-sdk project started as a target of refactoring, that moved reusable logic from app-template, so other apps can use it. Some apps, like checkout, are not based on app-template, but they still need to implement some app's interface.

Ongoing problems

app-template without clear boundaries

saleor-app-template is growing. We don't have a clear line what it should look like and what do we want to end up with.

We do want to explore more areas of apps (like queues integrations), but it's not possible to put everything in one project. It will no longer be a template but, rather a huge example project.

app-template doesn't have a line between app code and Saleor details

Saleor provides an interface that must be met when developing apps. There are specific endpoints (eg /register), manifests, etc. This is a subject of documentation and architecture diagrams and must be minimalistic.

Currently, app template mixes Saleor implementation details with example code. As a user, it's really hard to understand what code can be deleted and what is required for the app to be working.

app-template updates

app-template is a boilerplate code, that doesn't work well with updates. It requires a back-merging the original boilerplate, which is very fragile. Not only will limit git history and cause conflicts, but also lock us from introducing app-template with breaking changes.

The community moved from boilerplate solutions and tools like Yeoman aren't so popular anymore for end users

app-sdk doesn't have a release plan and focuses on API

app-sdk is now the target of refactoring, so we have only reusability in our mind, moving code there. It's risky, because this is a public SDK, meaning we can't export too many symbols, otherwise they will be used and we can't introduce breaking changes soon.

app-sdk requires a clear plan as an application toolkit used by Saleor internally but also - in the community.

lack of tests

app-sdk is not tested, which is not acceptable considering this is a public API

low debugability

app-sdk doesn't have explicit checks and logging, which is required in dev mode to early show problems

Proposed solutions

app-sdk vision

Implementation details hidden in SDK

We should aim to hide Saleor implementation details in app-sdk. We shouldn't require people to understand deep logic and details of how Saleor works. Basic docs with architecture diagrams should be enough to write app. Rest is SDK.

Example:

// pages/register.ts

import {createRegisterHandler} from '@saleor/app-sdk/nextjs';

export default createRegisterHandler(/* options */);

Frozen API from v1

Before v1.0.0 we can focus on extracting logic from app-template to SDK, but before official v1 release we must decide which APIs are exported and which are hidden. Only exported ones are subject of freezing.

Further releases can be classic Semver. Breaking changes introduces v2 release, most likely with updated app-templates by Saleor.

Heavily tested

Every piece of SDK must be deeply tested. Every bug found must be proven be reproduction test and fixed.

Debuggability

We will have a little more sophisticated logger that will:

1. In NODE_ENV !== 'production' show explicit error messages, links to docs and guides.
2. In NODE+ENV === 'production' hide error messages

We can use DEBUG package or something similar to allow users to choose logs scope

Explicit targets

app-sdk can work with Node, Next, Browser and later in other environments. We can think of having specific packages for that (eg @saleor/app-sdk-remix) but also we can have then scoped (@saleor/app-sdk/remix). It's important to have a clear line of targets, so:

• Browser code doesn't break Node, etc.
• Code is tree-shakable

app-template vision

Library of templates

Having a rich app-sdk, we can maintain not one, but a set of app-templates. They can be inspired by Remix Stacks, but also Next Examples.

Each template can be a part of Marketplace to be spawned from UI, or run via CLI (saleor app create sqs --template saleor-app-template-sqs).

Example templates can by literally anything and they can be created by the community.

They can be based on the business problems (app template that subscribes on some webhook) but also tech stack (example of db connection, example with Remix or Deno etc).

Lean templates

While all Saleor logic is moved to SDK, we no longer have bloated code. The template will literally be "hello world" apps and it will be very explicit that code is an example that can be deleted. In JSDOC comments we can mark usage of critical parts, that can't be removed or app breaks.

CLI app doctor

We can create a script (can be part of saleor-cli) that will validate if the app meets Saleor's interface (check for endpoints existence etc)

Template updates with SDK

The template will be versioned/tagged and it will require (in package.json) a specific SDK version range. We can ship bug fixes with patch/minor updates with simple package updates.

When SDK gets updated, we will write a migration guide (one day maybe code gens) to update stale APIs.

Templates maintained by Saleor will be version-locked with SDK, so when SDK enters v3, our templates will be released with the v3 tag.

[witoszekdev]

"CLI app doctor" idea is brilliant - it reminds me of Stoplight's Prism library that validates if your API matches OpenAPI specification ❤️

[lkostrowski]

After proposal from @krzysztofwolski - we should probably merge app-bridge to app-sdk. The line between them are blurred. Initially bridge was meant to be browser, sdk - node. However, many parts are isomorphic, so we can simplify and merge packages.

[korycins]

Did you check our python app framework? It is something already production tested (afaik).
https://mirumee.github.io/saleor-app-framework-python/
I think it is worth at least to check the docs/repo