Local Development

Setting up a local development environment for shop apps requires your application to be reachable from the internet, since VARIO Cloud needs to send webhooks and load your UI via iframe.

Making Your App Publicly Reachable

Your app must be accessible over HTTPS for VARIO Cloud to communicate with it. During local development, use a tunneling service to expose your local server.

Using ngrok

ngrok is the recommended tunneling tool:

# Install ngrok (macOS)
brew install ngrok

# Start a tunnel to your local app
ngrok http 443

ngrok will output a public HTTPS URL like https://abc123.ngrok.io. Use this URL in your app-manifest.json:

{
  "rootUrl": "https://abc123.ngrok.io/",
  "pcInstallationUrl": "https://abc123.ngrok.io/ui/install.html",
  "pcInstallationDeletionUrl": "https://abc123.ngrok.io/ui/uninstall.html",
  "pcManifestUrl": "https://abc123.ngrok.io/manifest"
}

The ngrok URL changes each time you restart the tunnel (unless you have a paid plan with reserved domains). Update your manifest URLs accordingly during development.

Using a Dev Server with a Fixed Domain

If your development machine has a static IP or domain name, you can skip tunneling and point your manifest URLs directly to your machine. Make sure HTTPS is configured (e.g., via a reverse proxy with Let's Encrypt).

Starting the Development Server

# Start in development mode
npm run dev

This starts the Express server on the configured port (default: 443). The framework serves your frontend files from the frontend/ directory and exposes your API routes.

Debugging

Logging

Use the framework's log() function to write structured log messages:

const { log } = require('@vario-software/vario-app-framework-backend/utils/logger');

// Log levels: DEBUG, INFO, WARN, ERROR
await log('Processing article sync', 'services/sync', 'DEBUG');
await log('Article synced successfully', 'services/sync', 'INFO');
await log('Rate limit approaching', 'services/sync', 'WARN');
await log('Failed to sync article', 'services/sync', 'ERROR');

Log messages include the tenant ID and request ID automatically, making it easy to trace requests across services.

Inspecting Webhooks

When debugging webhooks, log the full request body to see the payload:

app.apiServer.post('/webhooks/article-update', async (req, res) =>
{
  await log(
    `Webhook payload: ${JSON.stringify(req.body, null, 2)}`,
    'webhooks',
    'DEBUG'
  );

  res.status(200).send({ success: true });

  // ... process the webhook
});

Testing Webhook Delivery

You can trigger webhooks manually by modifying data in VARIO ERP:

1. Open the VARIO ERP UI

2. Navigate to an article

3. Make a change (e.g., update the description)

4. Save — this triggers the article.update webhook

Watch your server console for the incoming webhook request.

Using ngrok's Inspect Interface

ngrok provides a web interface at http://localhost:4040 where you can:

• See all incoming HTTP requests

• Inspect request headers and body

• Replay requests for debugging

• View response codes and timing

This is particularly useful for debugging webhook payloads and installation flows.

Environment Variables

You can use environment variables for configuration that differs between environments:

Variable	Description	Default
PORT	Server port	443
NODE_ENV	Environment mode	development
WEBHOOK_BASE_URL	Override webhook callback URL	App's root URL

The WEBHOOK_BASE_URL environment variable is useful when your webhook endpoint differs from your app's root URL, for example when running behind a reverse proxy.

Common Issues

"App not reachable" During Installation

• Make sure your tunnel is running and the URL in the manifest is correct

• Verify HTTPS is working (VARIO Cloud requires HTTPS)

• Check that your server is actually listening on the configured port

Webhooks Not Arriving

• Confirm the webhook was registered during installation (check logs)

• Make sure your tunnel URL hasn't changed since installation

• Verify the webhook endpoint path matches what you registered in the migration

Token Errors (401)

• The offline token may have expired — try reinstalling the app

• Make sure app-client.json contains the correct credentials

• Check that the app is properly registered in the Admin Center