Build a React app from npm

Create a frontend for your purchased Pikbase workspace using the published @gsb-core/cli and @gsb-core/starter packages. You do not need the platform monorepo, local package links, or a separate backend server.

Choose and provision your workspace

Register an Account identity, choose a paid workspace edition, review its actual price and billing term, and complete checkout. Wait until the workspace shows Ready. Payment confirmation alone does not prove provisioning finished.

Keep the workspace code and the workspace administrator identity you chose during purchase. Your Account identity and your workspace administrator are separate contexts; use the administrator credentials for CLI initialization. Open the ready workspace's details and select Start building your app for its exact command.

Workspace edition	Suggested frontend profile	Starting experience
Core	core	Workspace, profile, and installed-entity screens
Corporate	corporate	Corporate ERP screens backed by installed ERP contracts
SaaS	saas	Customer and operator SaaS surfaces backed by installed SaaS contracts

Profiles are frontend choices, not purchases or permission grants. Choose a different profile only when its required contracts are installed in your workspace. Installing a React package does not install backend entities, business functions, or workflows. Compare the workspace editions before purchase.

Prerequisites

Use Node.js 20.11 or newer, pnpm 9.15 or newer, and Git. Install pnpm using its supported installation method and confirm node --version, pnpm --version, and git --version work. Use localhost, not 127.0.0.1, for local browser validation.

Public package access does not require an npm login. The packages remain proprietary: use and customization require a valid entitlement under their included commercial license. Retain the license and notices; npm availability is not an open-source grant.

Install the published CLI

The commands below target CLI 0.1.2, the verified compatibility and workspace administrator authorization repair release. Do not use CLI 0.1.0: its pinned MCP dependency prevents startup. CLI 0.1.1 starts but can reject a correctly provisioned workspace administrator during initialization.

pnpm add --global @gsb-core/[email protected]
gsb --help
gsb workspace init --help

If pnpm reports no global binary directory, run pnpm setup, open a new terminal, and retry. Alternatively, use pnpm dlx @gsb-core/[email protected] in place of gsb. The CLI includes the starter package; there is no separate template download.

Initialize the selected workspace

Replace yourcode with the code shown in workspace details. Run from the parent directory where you want your new project. The destination must be new or empty.

gsb workspace init my-workspace-app --workspace yourcode --profile core --starter-version 0.1.0

For Corporate use --profile corporate; for SaaS use --profile saas. --tenant is an alias for --workspace; do not supply conflicting selectors.

When prompted, sign in with the selected workspace's administrator email, password, and MFA code if required. Type secrets at the terminal prompts, never in command arguments or source files. Initialization requires backend-verified system administrator access. Review the workspace code, API location, frontend profile, starter version, and planned operations before approving.

The CLI checks the workspace, copies the declared starter files, writes its workspace binding, installs dependencies with pnpm, checks TypeScript, builds the frontend, and initializes Git. It does not purchase a workspace or upgrade its backend edition. Normal installs outside the platform monorepo resolve dependencies from npm, not local workspace links. Keep the generated lockfile for reproducible installs.

For a reviewed noninteractive run, --yes approves initialization. A --dry-run prints a plan without creating the app or installing dependencies, but needs an existing authenticated CLI context. --resume is only for a matching interrupted initialization, not an overwrite or an upgrade of an existing application.

Run and verify

cd my-workspace-app
pnpm dev --host localhost --port 5173 --strictPort

Open http://localhost:5173, sign in to the workspace, and verify its code and installed entities. Hot reload is disabled; reload manually after edits. If the port is occupied, choose another port. After customization, run:

pnpm typecheck
pnpm build
pnpm preview --host localhost --port 4173 --strictPort

Test the production preview too: sign in, open a real record you are permitted to read, make an authorized change, and reload to verify persistence. Empty data is not proof of a failed install; inspect installed definitions and user permissions. Never replace missing contracts with fake data or local persistence.

Customize the React boilerplate

The generated app is your composition layer. Edit your project, not node_modules.

Goal	Generated file
Add a page and navigation entry	src/app-routes.tsx
Compose edition screens and branding	src/profiles/core.tsx, corporate.tsx, or saas.tsx
Change theme and typography	tailwind.config.ts, src/styles.css
Map configured SaaS payment providers	src/payments.ts
Inspect the selected workspace/API binding	src/workspace-binding.ts

For example, replace the empty appRoutes array while retaining its existing type imports:

export const appRoutes: readonly AppRoute[] = [
  {
    path: "/reports",
    title: "Reports",
    access: "signed-in",
    navLabel: "Reports",
    render: ({ session }) => (
      <p>
        Reports for{" "}
        {session.status === "authenticated" ? session.user.name : ""}
      </p>
    ),
  },
];

Reload and open /reports. Route visibility is not authorization: every data operation still needs Core permissions. Use the supplied workspace reader/writer or the established Entity Service and Entity Definition Service clients for real data. Do not introduce frontend API proxies, duplicate business logic, or secrets in VITE_* variables; those variables are compiled into the browser bundle.

Core SDK and React libraries

For definition-backed create, view, and update screens, follow Generate forms from entity definitions. It explains GsbForm, record loading, field customization, and the save callback boundary.

@gsb-core/core is the framework-independent SDK: models, types, service clients, API contracts, configuration, and utilities. It is not an aggregate package containing every React feature. The starter installs the packages required by its profile. For an existing TypeScript app, install the SDK with:

pnpm add @gsb-core/[email protected]

Use the Entity Service query reference and schema design guide for backend request contracts. Extend the generated authentication and client wiring rather than creating parallel sessions or embedding administrator tokens in the frontend.

Package	Responsibility
@gsb-core/app-kit	Application composition and host adapters
@gsb-core/react-auth	Authentication, session, and profile surfaces
@gsb-core/react-ui	Page layouts, themes, and loading/error/empty states
@gsb-core/react-components	Shared UI primitives
@gsb-core/react-forms	Definition-backed form composition
@gsb-core/react-data-table	Data-table and record-list presentation
@gsb-core/react-erp	ERP service and screen composition
@gsb-core/react-saas	SaaS registration, billing, subscriptions, and team surfaces
@gsb-core/react-paddle	Paddle browser checkout adapter
@gsb-core/react-workflow	Workflow-related React capabilities

Install only packages your code imports and use their exported types and composition APIs. For example, pnpm add @gsb-core/[email protected] adds a table library; it does not grant access to records or create a business schema. Monorepo-only @gsb-core/feature-* packages are private and are not dependencies for external apps.

Backend Core packs and libraries

A backend resource pack is different from an npm package. Packs carry selected definitions, code libraries, functions, workflows, permissions, and other approved backend assets into an authorized workspace. Your purchased edition is provisioned through Core; do not manually reinstall a canonical pack just to generate a frontend.

@gsb-core/source-pack contains typed resource-pack validation contracts. Adding it with pnpm does not install a pack or automatically make every backend library available. Inspect the actual installed contracts in your workspace. For authorized backend customization, gsb workspace checkout --workspace yourcode checks out the workspace assets; it does not generate a React app. Use a dedicated backend working directory and follow backend source control.

For pack creation, explicit asset-family selection, approved installation, and job verification, follow CI/CD, deployment, and seeds. There is no general gsb install core-pack command. Do not treat a job being accepted as proof its resources were installed, or assume a pack contains every library.

Troubleshooting and updates

• Workspace not ready: return to the paid order's setup page. Do not pay again or create another order merely because provisioning is pending.
• Administrator access required: use the administrator for the selected workspace, not an unrelated Account or customer identity.
• Authentication expired: run gsb init --workspace yourcode interactively to refresh CLI authentication, then retry initialization.
• Destination not empty: choose a new directory. Use --resume only for the matching staged initialization reported by the CLI.
• npm dependency failure: check registry connectivity and the requested published versions. Do not substitute link: or workspace:* dependencies in an end-user app.
• Missing ERP/SaaS capability: confirm backend contracts and the purchased edition; installing frontend packages cannot supply a missing backend operation.

Commit the app and lockfile, not credentials. Review package release notes and license terms before updates; update deliberately, then rerun types, build, and real-workspace checks. Do not rerun initialization over your customized project. Finish with the production readiness checks.