Getting Started

This guide walks you through setting up your local development environment and deploying your first Magic App.

Install the Claude Code Plugin

The magic-reports plugin adds Magic App development capabilities to Claude Code. It includes the full API reference, templates, and deployment commands.

/plugin marketplace add entrinsik-org/claude-plugins
/plugin install magic-reports@entrinsik-plugins

Once installed, Claude can help you build apps, query the API, and troubleshoot issues.

Scaffold a New Project

Create a new Vite project and initialize it for Magic App development:

# Create a vanilla Vite project
npm create vite@latest my-app -- --template vanilla

# Navigate to the project
cd my-app

# Install the plugin and initialize as a Magic App
npm install @entrinsik/vite-plugin-informer
npx informer-init

The init command will:

1. Add @entrinsik/vite-plugin-informer to devDependencies
2. Update vite.config.js to include the Informer plugin
3. Create .env and .env.example with connection settings
4. Create informer.yaml for API access and roles configuration
5. Add deploy and workspace:* scripts to package.json
6. Update .gitignore to exclude .env

Project Structure

After initialization, your project will have:

my-app/
├── .env                    # Connection settings (not committed)
├── .env.example            # Template for connection settings
├── informer.yaml           # App configuration (access rules, roles)
├── package.json            # Project metadata + informer section
├── vite.config.js          # Vite config with informer() plugin
├── public/
│   └── favicon.svg         # App icon (512x512, duotone recommended)
├── index.html              # Main HTML file
├── main.js                 # Entry point
├── styles.css              # Styles
├── server/                 # Server-side route handlers (optional)
│   └── index.js            # Example: GET / handler
└── migrations/             # SQL migration files (optional)
    └── 001-create-table.sql

App Configuration (informer.yaml)

The informer.yaml file declares which APIs your app can access and defines custom roles. Without the access section, all API access is blocked when the app runs in Informer.

# informer.yaml
access:
  datasets:
    - admin:sales-data
  queries:
    - admin:monthly-summary

roles:
  - id: viewer
    name: Viewer
    description: Read-only access to dashboards
  - id: approver
    name: Approver
    description: Can approve submitted items

See the informer.yaml Reference for the full format, including row-level security, credential injection, and variable reference.

Configure Connection

Edit .env with your Informer instance URL and credentials:

# Informer connection settings
INFORMER_URL=http://localhost:3000

# Option 1: API Key (recommended)
INFORMER_API_KEY=your-api-key

# Option 2: Basic auth
# INFORMER_USER=admin
# INFORMER_PASS=yourpassword

The Vite plugin uses these settings to proxy /api/* requests during local development.

Package.json Configuration

The informer section in package.json controls deployment metadata:

{
  "name": "my-app",
  "informer": {
    "name": "My App",
    "description": "A custom Magic App",
    "id": "a1b2c3d4-5678-90ab-cdef-123456789abc"
  }
}

Field	Description
name	Display name in Informer (falls back to package name)
description	App description
id	App UUID (auto-generated and saved after first deploy)
icon	Material icon name for the app (e.g., "bar_chart")

Your First Prompt

Now that your environment is set up, you can ask Claude Code to build your first app. Open Claude Code and try this:

Prompt:

"Build me a simple sales dashboard. Query the admin:sales-data dataset and show total revenue, order count, and average order value as metric cards. Add the dataset to informer.yaml. Keep it vanilla JavaScript with clean, modern styling."

Claude will:

1. Create the HTML structure with metric card layout
2. Write JavaScript to query the dataset API
3. Add styling with theme support (light/dark)
4. Update informer.yaml to grant dataset access
5. Set window.informerReady = true when data loads (for PDF export)

You can specify your preferred framework:

• "Use React with TypeScript"
• "Build it with Vue 3 and Tailwind CSS"
• "Keep it vanilla JS but use ECharts for charts"

The code examples in this guide show what Claude generates when you prompt it. You don't need to copy-paste — just describe what you want and let Claude build it.

Local Development

Start the development server:

npm install
npm run dev

This launches Vite with:

• Hot reload for instant feedback
• API proxy to your Informer server (with automatic auth)
• window.__INFORMER__ context mock (app ID, theme, etc.)
• Server route middleware (files in server/ are executed locally)

Your app will be available at http://localhost:5173 (or the next available port).

Iterating with Claude

Don't like something? Just tell Claude:

• "The chart colors don't match our brand — use #4f46e5 for primary"
• "Add a date range filter above the metrics"
• "Make the layout responsive for mobile"
• "Change the font to Inter"

Claude will update the code based on your feedback.

Theme Support

The Vite plugin injects a mock window.__INFORMER__ object during development:

window.__INFORMER__ = {
  report: { id: 'dev-local', name: 'Local Development' },
  theme: 'light'
}

To test dark mode, override in vite.config.js:

import informer from '@entrinsik/vite-plugin-informer';

export default {
  plugins: [informer({ mock: { theme: 'dark' } })]
};

In your code, respond to the theme:

const theme = window.__INFORMER__?.theme || 'light';
document.documentElement.setAttribute('data-theme', theme);

:root { --bg: #ffffff; --text: #1a1a1a; }
[data-theme="dark"] { --bg: #1e1e1e; --text: #e0e0e0; }
body { background: var(--bg); color: var(--text); }

Deploy to Informer

Build and deploy your app:

npm run deploy

This builds your project and uploads it to Informer. See Deployment for the full pipeline details.

Your app will be available at:

https://your-instance.entrinsik.com/reports/r/{owner}:{slug}

The deploy command saves the app UUID to package.json (informer.id) after the first deployment. This ensures subsequent deploys update the same app.

App Icon

Place a favicon.svg in your public/ directory. It will be deployed to the app's library root and used as:

• App gallery icon - Shown in desktop and mobile app galleries
• Browser tab favicon - Shown when the app is viewed in a browser

Icon Guidelines

• 512x512 viewBox, square (1:1 aspect ratio)
• Duotone style - One hue with full opacity for primary shapes, ~35% for secondary
• Self-contained background - Bake the background color into the SVG with rounded corners (rx="96")
• Bold, simple shapes - Recognizable at 70px (mobile icon size)

Example duotone icon:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
  <!-- Background with rounded corners -->
  <rect width="512" height="512" rx="96" fill="#064e3b"/>
  <!-- Secondary elements at 35% opacity -->
  <rect x="96" y="240" width="64" height="152" rx="10" fill="#6ee7b7" opacity="0.35"/>
  <!-- Primary elements at full opacity -->
  <rect x="176" y="160" width="64" height="232" rx="10" fill="#6ee7b7"/>
</svg>

Next Steps

Now that you have a working development environment, continue to KPI Dashboard to build your first data-driven app.