@vinadesignstore/create-app

Interactive pnpm dlx scaffolder for VNDS apps.

Usage

pnpm dlx @vinadesignstore/create-app

The command:

• opens a browser login against your VNDS auth server
• lets you create a new satellite app or choose an existing one
• for new apps, asks for one or more app URLs and derives allowed origins + callback URLs automatically
• installs @vinadesignstore/core-client
• writes shadcn-compatible button + card primitives and components.json
• scaffolds direct VNDS auth with /auth/callback
• optionally scaffolds a typed lib/config.schema.ts with zod
• optionally scaffolds a default-config seed script
• scaffolds /sign-in, /account, and /config-example

Auth flow

• simplest setup
• one VNDS session per browser profile
• scaffolded callback route: /auth/callback
• if you register a localhost app URL like http://localhost:3001, the scaffold updates pnpm dev to use that port so local callbacks stay aligned

Security model

The generated config helpers are designed so the VNDS app secret stays server-side.

• lib/vnds-config.ts is marked server-only and reads VNDS_CORE_API_KEY from env
• reads and writes against the auth server still require VNDS_CORE_APP_ID + VNDS_CORE_API_KEY
• the generated client example does not call the auth server directly
• client reads go through app/api/vnds/config/[key]/route.ts, which requires a signed-in VNDS user
• client writes go through the same local route, which requires a signed-in VNDS user plus one of these roles:
  • admin
  • owner
  • config-manager
• the generated write route also rejects cross-origin writes

That means installing the package alone does not grant config access. Access still depends on your app secret on the server and the viewer authorization checks in your own app.

Generated config usage

The generated app includes:

• lib/vnds-config.ts — server-side getConfig, setConfig, listConfigs, and deleteConfig
• app/config-example/page.tsx — server component examples for reading and writing config
• app/config-example/client-config-demo.tsx — client component examples for reading and writing config through a local route
• app/api/vnds/config/[key]/route.ts — local API wrapper for client-safe reads and writes
• .env.local.example with VNDS_CORE_CONFIG_NAMESPACE=<your-app-slug>
• AGENTS.md with project-local instructions for safely using VNDS auth and config helpers

Typical server usage inside the generated app:

import { getConfig, setConfig } from "@/lib/vnds-config";

const branding = await getConfig("branding");
await setConfig("branding", {
  appName: "My Satellite App",
  accent: "#7c3aed",
  supportEmail: "[email protected]"
});

Typical client usage inside the generated app:

const response = await fetch("/api/vnds/config/branding");
const currentConfig = await response.json();

await fetch("/api/vnds/config/branding", {
  method: "PUT",
  headers: {
    "content-type": "application/json"
  },
  body: JSON.stringify({
    value: {
      appName: "My Satellite App",
      accent: "#7c3aed",
      supportEmail: "[email protected]"
    }
  })
});

In the auth server admin, create app config rows in /admin/configs like this:

• choose your app from the namespace dropdown
• set key=branding
• keep environment=production or development
• save the JSON value

Typed config schema option

If you enable the typed schema option, the scaffold adds lib/config.schema.ts with:

• configSchemas
• defaultConfigValues
• safeParseConfigValue
• formatConfigValidationErrors

The generated code then uses that schema in two places:

• server writes through setConfig(...)
• live client-side validation in /config-example

Edit lib/config.schema.ts to match your app's real config keys and shapes.

Default config seed example

If you enable the seed option, the scaffold adds scripts/seed-vnds-config.ts.

Run it with:

pnpm dlx tsx scripts/seed-vnds-config.ts

A typical app-specific next step is to replace the default branding seed with real config for your app, for example:

const defaults = {
  branding: {
    appName: "Storefront",
    accent: "#0f172a",
    supportEmail: "[email protected]"
  },
  checkout: {
    requirePhoneNumber: true,
    allowedCountries: ["US", "CA"]
  },
  featureFlags: {
    wishlist: true,
    loyalty: false
  }
};

Then seed those defaults into the current app namespace before your team starts using the app.

Current assumptions

• run it inside an existing Next.js App Router project
• use pnpm as the package manager
• use direct VNDS auth for sign-in and session cookies
• for existing apps, paste the current VNDS_CORE_API_KEY manually because the auth server does not store retrievable secrets