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:
- In
NODE_ENV !== 'production' show explicit error messages, links to docs and guides.
- 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.
Context
app-sdkproject started as a target of refactoring, that moved reusable logic fromapp-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-sdkdoesn't have a release plan and focuses on APIapp-sdkis 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-sdkrequires a clear plan as an application toolkit used by Saleor internally but also - in the community.lack of tests
app-sdkis not tested, which is not acceptable considering this is a public APIlow debugability
app-sdkdoesn't have explicit checks and logging, which is required in dev mode to early show problemsProposed 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:
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:
NODE_ENV !== 'production'show explicit error messages, links to docs and guides.NODE+ENV === 'production'hide error messagesWe 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: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.