@appaflytech/create-wappa

Scaffold a new Wappa CMS project in seconds — Next.js 14 or Expo React Native, with optional gluestack-ui v4 or plain Tailwind/NativeWind.

Usage

npm create @appaflytech/wappa@latest
# or
npx @appaflytech/create-wappa@latest
# or
pnpm create @appaflytech/wappa@latest
# or
bunx @appaflytech/create-wappa@latest

Running the command launches an interactive prompt:

◆  create-wappa

◇  Project type?
│  ● Web (Next.js 14)  ○ Mobile (Expo React Native)

◇  UI framework?
│  ● gluestack-ui v4 (Recommended)  ○ Tailwind CSS only

◇  Project name?
│  my-wappa-app

◇  Target directory?
│  my-wappa-app

◇  Wappa site key?
│  my-site-key

◇  Wappa API URL?
│  https://api.example.com

◇  CDN URL?
│  https://cdn.example.com

◇  Default language?
│  ● Turkish (tr-tr)  ○ English (en-us)  ○ ...

◆  ✓ Project "my-wappa-app" created successfully!

Next steps:
  cd my-wappa-app
  npm install
  npm run dev

What gets scaffolded

Web (Next.js 14)

| UI Framework | Stack | | --------------------- | ---------------------------------------------------------------------------- | | gluestack-ui v4 | Next.js 14 · App Router · gluestack-ui v4 · NativeWind tokens · Tailwind CSS | | Tailwind CSS only | Next.js 14 · App Router · Tailwind CSS · plain HTML components |

Scaffolded files include:

• app/layout.tsx — root layout (with GluestackUIProvider if gluestack)
• app/page.tsx — entry page using WapScreen
• components/WapScreen.tsx — Wappa page renderer
• core/render.tsx — Wappa component render system
• components/index.tsx — 36 component registry
• services/contextService.ts — @appaflytech/wappa-client integration
• store/store.ts — Zustand store
• next.config.js, tailwind.config.js, tsconfig.json, .env, .gitignore

Mobile (Expo React Native)

Mobile projects are a thin shell over @appaflytech/wappa-mobile-ui, which provides the server-driven render engine + the built-in component library. The scaffold only adds the app wiring and a handful of custom components, so the UI-framework choice no longer changes the mobile component source.

Scaffolded files include:

• app/_layout.tsx — root layout; imports @/components to register components
• app/index.tsx / app/[...pathname].tsx — screens using WapScreen
• components/WapScreen.tsx — page loader; calls render() from the package
• components/index.tsx — registerComponents() wiring for the custom components
• components/ui/* — custom components NOT in the package (box, card, table, charts, drawer, …)
• services/contextService.ts — @appaflytech/wappa-client integration
• store/store.ts — Zustand store + setWappaStore() (hands state to the engine)
• utils/path.ts — CDN image helpers
• CUSTOM_COMPONENTS.md — guide for adding/overriding components
• app.json, babel.config.js, metro.config.js, tailwind.config.js, .env

The render engine, built-in components (button, input, modal, image, lists, camera, …), navigation, overlays and buses all live in the package — they are not copied into the project.

Custom components

Add your own components (or override built-ins) with registerComponents() in components/index.tsx. Every scaffolded project ships a CUSTOM_COMPONENTS.md with a full walkthrough (create → register → use from the page schema).

Included components

Web (36 components)

box · center · hstack · vstack · grid · pressable · heading · paragraph · icon · image · video · embed · button · link · fab · card · card-list · avatar · badge · divider · data-table · skeleton · spinner · alert · progress · toast · accordion · tabs · modal · drawer · actionsheet · menu · alert-dialog · tooltip · form-control · input · switch · checkbox · radio · textarea · slider · select · date-picker

Mobile (29 components)

box · center · hstack · vstack · grid · pressable · heading · paragraph · icon · image · video · button · link · fab · card · card-list · avatar · badge · divider · skeleton · spinner · alert · progress · toast · accordion · tabs · modal · actionsheet · menu · alert-dialog · tooltip · form-control · input · switch · checkbox · radio · textarea · slider

Environment variables

The generated .env file contains:

# Web (Next.js)
NEXT_PUBLIC_WAP_SITE_KEY=your-site-key
NEXT_PUBLIC_WAP_API=https://api.example.com
NEXT_PUBLIC_WAP_CDN=https://cdn.example.com
NEXT_PUBLIC_WAP_LANGUAGE=tr-tr

# Mobile (Expo)
EXPO_PUBLIC_WAP_SITE_KEY=your-site-key
EXPO_PUBLIC_WAP_API=https://api.example.com
EXPO_PUBLIC_WAP_CDN=https://cdn.example.com
EXPO_PUBLIC_WAP_LANGUAGE=tr-tr

How it works

The CLI uses @appaflytech/wappa-client to fetch page context from Wappa CMS. Each page renders dynamically via the Wappa render system — a component registry that maps Wappa widget types to your UI components:

// core/render.tsx (simplified)
import { components } from "@/components";

export function WapRender({ elements }) {
  return elements.map((el) => {
    const Component = components[el.type];
    return Component ? <Component key={el.id} {...el.props} /> : null;
  });
}

You can extend the registry by adding components to components/index.tsx.

Requirements

| Web | Mobile | | ----------- | ------------------ | | Node.js 18+ | Node.js 18+ | | Next.js 14 | Expo SDK 51+ | | React 18 | React Native 0.74+ |

Publishing (maintainers)

npm run build
npm publish --access public

License

MIT © appaflytech