Full App Scaffold (Project-Level)

[lasomethingsomething]

User story

As an app developer, I want shopware app create to scaffold a complete runnable app project (not just the manifest), so I can start development without manually setting up the app backend and local networking.

Problem it solves

shopware-cli app create currently only generates the Shopware-side registration (manifest.xml). It does not scaffold the actual app project (e.g. Node/PHP backend, webhook handling, OAuth setup). This leaves developers only halfway done and struggling with local service setup, searching through docs (example apps exist in the Node.js SDKs) to understand the manifest. They must manually:

• Create the app service project
• Configure webhooks and callback URLs
• Set up Docker networking
• Make the app reachable from the browser and the shop

Plugins are much easier because everything runs inside the shop.

Acceptance criteria

• shopware app create my-app creates:
  • manifest.xml
  • A backend project scaffold (Node or minimal HTTP server)
  • Predefined webhook endpoints
  • Dev config
  • Templates contain schema JSON files so that people know that they should update it when they're changing the API with their app
• No manual manifest editing required to boot.
• App can start with a single command (npm run dev or similar).
• accommodate the tech stack they want to use

[SpiGAndromeda]

An additional case for this Story (or maybe a new one) would be to evaluate if a plugin could be migrated to an app in order to reduce the maintenance burden that Shopware-dependent code might introduce. Many plugins are "just" integrations of external Systems/Providers into Shopware. Not all of these intgerations require access to the PHP stack of Shopware and could be apps as well. Also apps are fully supported in SaaS.

I am not sure if this is in-scope of the Shopware CLI as its a task that is not entirely deterministic. Used extension points have to be identified and compared to extension points of the App system. If the plugin contains business logic, it has to be evaluated if this could moved to an app server which does the "heavy lifting".

[gweiermann]

Me and the admin team discussed how a solution could look like (original issue: shopware/shopware#15517):

In the JavaScript ecosystem, developers are used to running a simple npm create command to scaffold and bootstrap a new project.

However, since creating a Shopware app also requires interaction with the Shopware backend (e.g., manifest generation and app registration), we discussed introducing a mechanism where either:

• the npm create command, or
• the shopware-cli

generates a payload or connection URL that allows the Shopware backend and the local app server to exchange the necessary information automatically.

To further improve the developer experience, the shopware-cli functionality could also be exposed within the Shopware Admin interface.

Below is a more detailed outline of the proposed vision, explained by using the GUI.

Option A: NPM generates the payload

The developer starts locally:

> npm create shopware-app
> cd shopware-app
> npm install
> npm run connect --name MyExampleApp

CLI output:

Here is your connection URL:
http://localhost:3000/connect?secret=randomlygenerated

Go to:
Shopware Admin > Extensions > Add Dev App
Paste the URL above

After confirmation in the Admin:

Connected successfully!
> npm start

This approach keeps the workflow familiar for JavaScript developers while enabling the backend to handle app registration and manifest generation automatically.

Option B: Admin generates the payload

The developer starts in the Shopware Admin:

Shopware Admin → Extensions → Add Dev App

They enter:

• App Name
• Optional configuration options

The Admin then generates ready-to-use CLI commands:

> npm create shopware-app \
  --connect http://localhost:8000/connect-app \
  --secret=randomlygenerated \
  --name MyExampleApp

> cd shopware-app
> npm install
> npm start

This approach shifts the entry point to the Shopware instance and provides developers with a fully preconfigured setup command.

What Should npm create shopware-app Do?

(Note: shopware-app is just a placeholder name.)

The generator should:

• Scaffold a complete boilerplate project
• Bootstrap meteor-admin-sdk for the Admin extension frontend
• Bootstrap app-sdk-js for the backend
• Provide a ready-to-run “Hello World” example
• Establish the connection to the Shopware instance
• Trigger backend-side generation of manifest.xml during registration
• Eliminate the need to manually execute backend commands inside the Shopware environment (when using the GUI)

The goal is a true zero-friction developer experience.

Known Challenges & Open Questions

1. Docker & Network Barriers

Common examples:

• registrationUrl may require host.docker.internal
• app-base-url may require localhost

These environment-specific differences are confusing and error-prone.

Question:
How can we detect or abstract these networking edge cases automatically to reduce setup friction?

2. Remote Development / Tunneling Barrier

If the Shopware instance is not running locally, developers currently need a tunneling service (e.g., ngrok).

This introduces additional complexity for something as simple as a Hello World example.

Possible Solutions for the Tunneling Problem

Option A: Official Shopware Tunnel Service

Instead of:

http://localhost:8000/connect-app

Use something like:

https://connect-app.shopware.com/<unique-id>

Shopware could provide a managed tunneling solution specifically for development apps, removing the need for third-party services.

Option B: WebSocket-Based Dev Tunnel

Instead of relying on HTTP webhooks:

• The app establishes a persistent WebSocket connection to the Shopware instance
• Webhooks are delivered through this connection
• No local port forwarding is required

This could significantly reduce local setup friction and improve reliability in development environments.

Notes

• All URLs and commands shown are illustrative and may not reflect actual backend routes.
• This proposal targets development environments only.
• This is not a finalized design, but a starting point for discussion.
• While currently focused on app-sdk-js, the same concept should ideally be supported for the php-sdk as well.

[shyim]

and where it will run at the end? Of course we can use our app-js-sdk. But which Webserver Hono/Express/Fastify and and.
Serverless? Regular long running progress?
Which databases will we're using to store it? SQL based (which dialect sqlite/mysql/postgres), or document storage, or key value just?
Where do we deploy it?

All those questions need to be answered when you want to build something, when you start with a simple document based DB, and later for migrate, you may can delete everything and start again.

[gweiermann]

This is meant to be a starting point. It’s much easier to begin when the basic setup is already in place. Of course, questions about deployment and databases matter — but those come later. The first goal should be to get a simple “hello world” running, without having to build and configure everything from scratch.

From there, the documentation can guide the next steps:

• If you just want to experiment and get familiar with the ecosystem, you shouldn’t have to think about hosting, databases, or deployment yet.
• The docs can then explain how to evaluate and choose a web server/hosting setup, a database, and a deployment strategy when you’re ready.

Without an initial setup command, the entry barrier becomes much higher — and you’re forced to deal with complex architectural decisions before you’ve even seen the application running.

This is how other frameworks handle it. Next.js, for example, provides a base template to get started quickly, but doesn’t force a specific database choice (aside from some deployment recommendations aligned with their ecosystem).

Now imagine following a Next.js or Nuxt.js tutorial where you had to manually copy every file from the documentation into an empty project just to get started. That would significantly slow down onboarding and make the first experience unnecessarily frustrating.

A good starter setup lowers friction, encourages exploration, and makes adoption easier.

[gweiermann]

Soner (@shyim) I've put together a proof of concept to illustrate the idea that I've proposed:

create-dev-app-poc.mov

The goal is to make app setup as fast and straightforward as possible, so developers can focus on more important aspects like databases.

Please share your opinions 🙏

[lasomethingsomething]

Hi Gerrit Weiermann (@gweiermann), thanks for moving this forward. We ran through this at the daily:

• dev won't be working from the Admin but with a CLI/TUI; how might this experience look given those conditions?
• would need to choose what to do with the app (there are two primary paths; the current app base guide is a bit muddled here, but basically Path A for apps without a backend, and Path B ("the hardcore way") with a backend.
• we also need to think about this in terms of being clear about how to provide requirements for users given which path they choose and the ability to customize without either being too strict or too loose

A little journey ahead of us, but let's keep the conversation going!

[jleifeld]

Soner (@shyim) I've put together a proof of concept to illustrate the idea that I've proposed:

create-dev-app-poc.mov
The goal is to make app setup as fast and straightforward as possible, so developers can focus on more important aspects like databases.

Please share your opinions 🙏

I really love the solution. It removes a lot of complexity most people currently have setting up a new app.

[gweiermann]

somethings (@lasomethingsomething), thank you for your feedback!

Disclaimer: I’m using the-cli as a stand-in for shopware-cli since I don’t know the exact syntax. The intention is that the-cli reflects the semantics of shopware-cli.

1. CLI alternative

This would essentially follow the same process, but via a CLI:

# we are inside the shopware instance

$ the-cli create app --name=MyDevApp

Here’s your command to create your app:

  npm create shopware-app \
    --name MyDevApp \
    --connect http://localhost:8000/api/_action/dev-app/connect \
    --token=••••••••••••••••••••••••••••••

Waiting for your app to connect...
✔ Connected! Your app is now linked.

Alternatively, the flow could be inverted so that no interaction with the Shopware instance is required:

# we are outside, not inside the shopware instance

$ the-cli login

Opening browser for OAuth login...
Waiting for authorization...
✔ Logged in as john.doe@example.com

$ the-cli create app --name MyDevApp

? Which backend do you want to use?
❯ ● Node.js (app-sdk-js)
  ○ PHP (php-sdk)

? Do you want to extend the admin?
❯ ● Yes
  ○ No

? Use Vue.js for the admin?
❯ ● Yes
  ○ No

? Do you want to extend the storefront?
  ○ Yes
❯ ● No

Scaffolding project...
Installing dependencies...
Configuring app...

Starting dev server...
✔ App registered at Shopware

  VITE v5.0.0  ready in 420 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

  watching for file changes...

The prompts shown here are placeholders (see point 3).

---

2.

• Path A (likely a niche case):
  The scaffold still provides a server to host the app. When publishing, the dev server is stripped away.

• Path B:
  Keep the backend as part of the project without stripping anything.

• Creating a plugin or app directly inside /custom/plugins/... or /custom/apps/... is out of scope for this proposal.

---

3.

This is a topic we have barely explored so far. The goal of our proposal was to outline a technical vision for bootstrapping an application with a single command, using a single project directory, without the need to switch between command lines or projects.

It is an important area that should be addressed as a next step. I am looking forward to supporting further discussions.

Oh, and also:

Let's not forget to improve the situation regarding port forwarding/tunnels: At the moment, a CLI won't solve the issue. In my first comment, I made two suggestions for how to solve it.