Version: v1 (Current)

Getting Started

This guide walks you through installing the GxP Toolkit and creating your first plugin project.

Prerequisites

Before you begin, ensure you have:

Node.js 18+ - Download Node.js
npm 9+ - Included with Node.js
Code editor - VS Code recommended

Installation

Option 1: Global Installation (Recommended)

Install the toolkit globally to use the gxdev command anywhere:

npm install -g @gxp-dev/tools

Option 2: Project-Level Installation

Or install as a dev dependency in an existing project:

npm install --save-dev @gxp-dev/tools

Updating the Toolkit

# Update global installation
npm update -g @gxp-dev/tools

# Update project-level installation
npm update @gxp-dev/tools

After updating, run gxdev init in existing projects to sync dependencies, scripts, and config files.

Create a New Plugin

1. Initialize Your Project

Create a new plugin project using the interactive CLI:

gxdev init my-plugin

Or run without arguments to be prompted for a name:

gxdev init

2. Interactive Configuration

After the project files are created and dependencies installed, you'll enter an interactive configuration wizard:

──────────────────────────────────────────────────
📝 Configure Your Plugin
──────────────────────────────────────────────────

? App name
❯ my-plugin - From package.json
  Enter custom name

? Description
❯ A GxP kiosk plugin - From package.json
  Enter custom description

Use arrow keys to select options:

First option is prepopulated from package.json
Second option lets you enter a custom value

3. AI-Powered Scaffolding (Optional)

Next, you'll be asked if you want AI to help scaffold your plugin. The wizard detects which AI providers are available on your system:

──────────────────────────────────────────────────
🤖 AI-Powered Scaffolding
──────────────────────────────────────────────────
   Describe what you want to build and AI will generate
   starter components, views, and manifest configuration.

? Choose AI provider for scaffolding
❯ Skip AI scaffolding
  Claude - logged in
  Codex - logged in
  Gemini - via API key

If you select a provider, describe your plugin:

📝 Describe your plugin (what it does, key features, UI elements):
  (Press Enter twice when done)

  > A conference check-in kiosk with a welcome screen,
  > badge scanner input field, and confirmation display
  >

Supported AI Providers

Provider	Authentication
Claude	Claude CLI logged in (`claude login`)
Codex	Codex CLI logged in (`codex auth`)
Gemini	Gemini CLI, API key (`GEMINI_API_KEY`), or gcloud CLI

Setting up providers:

# Claude (uses your Anthropic account)
npm install -g @anthropic-ai/claude-code
claude login

# Codex (uses your OpenAI account)
npm install -g @openai/codex
codex auth

# Gemini CLI (recommended - uses your Google account)
npm install -g @google/gemini-cli
gemini  # First run will prompt for login

# Gemini (API key)
export GEMINI_API_KEY=your_google_ai_api_key

# Gemini (gcloud)
gcloud auth login

4. SSL Setup

Choose whether to set up SSL certificates:

──────────────────────────────────────────────────
🔒 SSL Configuration
──────────────────────────────────────────────────

? Set up SSL certificates for HTTPS development?
❯ Yes, set up SSL - Recommended for full feature access
  Skip SSL setup - Can be set up later with npm run setup-ssl

5. Start Development

Choose how to start the development server:

──────────────────────────────────────────────────
🚀 Start Development
──────────────────────────────────────────────────

? How would you like to start the development server?
❯ Start app - HTTPS dev server
  Start app with Mock API - Dev server + Socket.IO + Mock API
  Skip

6. Browser Extension (Optional)

If starting the app, choose to launch a browser with the GxP extension:

? Launch browser with GxP extension?
❯ Chrome - Launch Chrome with DevTools panel
  Firefox - Launch Firefox with DevTools panel
  Skip

Non-Interactive Mode

For CI/CD or scripting, use command-line flags:

# Basic creation
gxdev init my-plugin -d "My awesome plugin"

# With AI scaffolding (defaults to Gemini)
gxdev init checkin-kiosk -d "Conference check-in" \
  -b "A check-in kiosk with welcome screen and badge scanner"

# With specific AI provider
gxdev init checkin-kiosk -d "Conference check-in" \
  -b "A check-in kiosk" -p claude

Available providers: claude, codex, gemini

Your plugin is now running at https://localhost:3060 (or http://localhost:3060).

Project Structure

After initialization, your project looks like this:

my-plugin/
├── src/
│   ├── Plugin.vue          # Main plugin entry point
│   ├── DemoPage.vue        # Example component
│   └── stores/
│       └── index.js        # Store setup
├── theme-layouts/
│   ├── PublicLayout.vue    # Public-facing layout
│   ├── PrivateLayout.vue   # Authenticated layout
│   └── SystemLayout.vue    # System/admin layout
├── .claude/
│   ├── agents/
│   │   └── gxp-developer.md # Claude Code subagent
│   └── settings.json       # MCP server configuration
├── dev-assets/
│   └── images/             # Development placeholder images
├── app-manifest.json       # Plugin configuration
├── AGENTS.md               # Codex/AI agent instructions
├── GEMINI.md               # Gemini Code Assist instructions
└── .env                    # Environment variables

Add to an Existing Project

If you already have a Vue/Vite project, you can add the toolkit without scaffolding a new one:

cd ~/my-existing-project
gxdev init

When run in a directory with an existing package.json (and no project name argument), gxdev init will:

Add missing dependencies - Required packages and devDependencies are merged into your package.json
Update mismatched versions - Dependency versions are upgraded to match the toolkit's expected versions
Add npm scripts - Missing scripts like dev, build, dev-http are added
Back up your Vite config - Renames existing vite.config.js to vite.config.js.backup
Copy config files - app-manifest.json, .env.example, store setup, AI agent configs

It will not overwrite your source files (src/Plugin.vue, src/DemoPage.vue, theme-layouts/, etc.).

After init, install dependencies and start developing:

npm install
npm run dev-http

tip

The dev server serves index.html and main.js from the toolkit runtime by default — you don't need local copies. If your project requires custom versions, set USE_LOCAL_INDEX=true and/or USE_LOCAL_MAIN=true in your .env file (the corresponding local files must also exist).

Your First Edit

Open src/Plugin.vue and make a change:

<template>
  <div class="my-plugin">
    <h1 gxp-string="welcome_title">Welcome to My Plugin!</h1>
    <p>Edit this file to get started.</p>
  </div>
</template>

<script setup>
import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';

const store = useGxpStore();
</script>

The page automatically refreshes with your changes.

SSL Setup (Optional)

For HTTPS development (required for some platform features):

npm run setup-ssl

This uses mkcert to generate trusted local certificates.

Using the Interactive TUI

After creating your project, run gxdev without arguments from the project directory to launch the interactive Terminal UI:

cd my-plugin
gxdev

tip

After gxdev init completes, you'll be prompted to launch the TUI automatically. The TUI is for managing services within an existing project-use gxdev init from the CLI to create new projects.

The TUI provides:

Service management - Start/stop Vite, Socket.IO, extensions
Log viewing - Real-time logs from all services
Slash commands - Quick actions like /dev, /socket, /ext chrome

TUI Keyboard Shortcuts

Shortcut	Action
`Ctrl+1/2/3...`	Switch service tabs
`Ctrl+L`	Clear current log
`Ctrl+K`	Stop current service
`Ctrl+C`	Exit application
`Shift+↑/↓`	Scroll log panel
`Ctrl+↑/↓`	Jump to top/bottom of logs
`Mouse wheel`	Scroll log panel

Next Steps

Configure your app manifest - Set up strings, settings, and assets
Learn the GxP Store - State management and platform integration
Use Dev Tools - Debug and inspect your plugin
Build for platform - Prepare for production deployment

Common Commands Reference

# Development
gxdev dev                    # Start with Vite + Socket.IO
gxdev dev --no-https         # Start without SSL
gxdev dev --no-socket        # Start Vite only (no Socket.IO)
gxdev dev --with-mock        # Start with Mock API enabled
gxdev dev --chrome           # Launch with Chrome extension
gxdev dev --firefox          # Launch with Firefox extension

# Building
gxdev build                  # Build for production

# Utilities
gxdev datastore list         # List store variables
gxdev datastore scan-strings # Find hardcoded strings
gxdev socket list            # List socket events
gxdev assets generate        # Generate placeholder images

Prerequisites​

Installation​

Option 1: Global Installation (Recommended)​

Option 2: Project-Level Installation​

Updating the Toolkit​

Create a New Plugin​

1. Initialize Your Project​

2. Interactive Configuration​

3. AI-Powered Scaffolding (Optional)​

Supported AI Providers​

4. SSL Setup​

5. Start Development​

6. Browser Extension (Optional)​

Non-Interactive Mode​

Project Structure​

Add to an Existing Project​

Your First Edit​

SSL Setup (Optional)​

Using the Interactive TUI​

TUI Keyboard Shortcuts​

Next Steps​

Common Commands Reference​