Scaffolding New Xano Components

This guide explains how to create new Xano components using Xano Tools, from initial scaffolding to deployment.

Overview
Quick Start
Scaffolding a Registry
Creating Component Definitions
Writing XanoScript
Component Templates
Deployment Workflow
Best Practices

Overview

Xano Tools provides a component-based approach to creating new Xano functions, APIs, and other entities. Rather than generating boilerplate code directly, you:

Scaffold a registry - Create a component structure
Define components - Describe your component in JSON
Write XanoScript - Implement your business logic
Deploy via CLI - Install components to your Xano instance

This approach enables:

Reusability - Create once, deploy many times
Team sharing - Share components across projects
Version control - Track changes in Git
Dependency management - Handle complex component relationships

Quick Start

Create a New Function Component

Bash

# 1. Scaffold a new registry
caly-xano registry scaffold --output ./my-components

# 2. Navigate to the scaffolded registry
cd my-components

# 3. Serve the registry locally
caly-xano serve registry --path .

# 4. In another terminal, install to your Xano instance
caly-xano registry add sample-function \
  --registry http://localhost:5500/registry/definitions \
  --instance my-instance \
  --workspace main \
  --branch dev

Scaffolding a Registry

The Scaffold Command

Bash

caly-xano registry scaffold --output <path> [--instance <name>]

Options:

Option	Description
`--output <path>`	Where to create the registry folder
`--instance <name>`	Optional: associate with a Xano instance

Generated Structure

Code

my-components/
├── registry.json           # Registry configuration
├── items/
│   └── sample-function/
│       ├── definition.json # Component metadata
│       └── function.xs     # XanoScript code
└── README.md               # Documentation

Registry Configuration

The registry.json file defines your registry:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry.json",
   "name": "my-components",
   "description": "My reusable Xano components",
   "items": ["items/sample-function/definition.json"]
}

Creating Component Definitions

Function Component

Create items/my-function/definition.json:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry-item.json",
   "name": "my-function",
   "type": "registry:function",
   "title": "My Custom Function",
   "description": "A custom function that does something useful",
   "author": "Your Name <https://github.com/yourname>",
   "categories": ["utility"],
   "files": [
      {
         "path": "./function.xs",
         "type": "registry:function"
      }
   ],
   "postInstallHint": "Call this function from your API endpoints!"
}

API Group Component

Create items/user-api/definition.json:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry-item.json",
   "name": "api/user-management",
   "type": "registry:apigroup",
   "title": "User Management API",
   "description": "Complete CRUD API for user management",
   "files": [
      {
         "path": "./user-api.xs",
         "type": "registry:apigroup"
      }
   ],
   "registryDependencies": ["tables/user"]
}

Table Component

Create items/tables/user/definition.json:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry-item.json",
   "name": "tables/user",
   "type": "registry:table",
   "title": "User Table",
   "description": "Standard user table schema",
   "files": [
      {
         "path": "./user.xs",
         "type": "registry:table"
      }
   ]
}

Addon Component

Create items/addons/string-utils/definition.json:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry-item.json",
   "name": "addons/string-utils",
   "type": "registry:addon",
   "title": "String Utilities Addon",
   "description": "Common string manipulation utilities",
   "files": [
      {
         "path": "./string-utils.xs",
         "type": "registry:addon"
      }
   ]
}

Middleware Component

Create items/middleware/auth/definition.json:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry-item.json",
   "name": "middleware/jwt-auth",
   "type": "registry:middleware",
   "title": "JWT Authentication Middleware",
   "description": "Validates JWT tokens on incoming requests",
   "files": [
      {
         "path": "./jwt-auth.xs",
         "type": "registry:middleware"
      }
   ],
   "postInstallHint": "Set XANO_JWT_SECRET environment variable"
}

Task Component

Create items/tasks/cleanup/definition.json:

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry-item.json",
   "name": "tasks/daily-cleanup",
   "type": "registry:task",
   "title": "Daily Cleanup Task",
   "description": "Scheduled task for cleaning up old data",
   "files": [
      {
         "path": "./cleanup.xs",
         "type": "registry:task"
      }
   ]
}

Writing XanoScript

Getting Started

For XanoScript syntax and examples, refer to:

Official Xano Documentation https://docs.xano.com/xanoscript/vs-code#usage

Recommended Development Setup

Install Xano VS Code Extension - Best development experience

Extract existing code - Learn from your existing Xano functions:

Bash

caly-xano generate xanoscript --instance prod --workspace main --branch live

Study extracted files - Understand XanoScript patterns
Create new components - Apply patterns to new components

Example Workflow

Bash

# Extract XanoScript from existing project for reference
caly-xano generate xanoscript \
  --instance my-instance \
  --workspace main \
  --branch live

# Review extracted files
ls -la xanoscript/functions/

# Copy and modify for your new component
cp xanoscript/functions/example.xs my-components/items/my-function/function.xs

Component Templates

Organizing Multiple Components

Code

my-registry/
├── registry.json
├── items/
│   ├── auth/
│   │   ├── login/
│   │   │   ├── definition.json
│   │   │   └── login.xs
│   │   ├── register/
│   │   │   ├── definition.json
│   │   │   └── register.xs
│   │   └── middleware/
│   │       ├── definition.json
│   │       └── auth-middleware.xs
│   ├── utils/
│   │   ├── string-helpers/
│   │   │   ├── definition.json
│   │   │   └── helpers.xs
│   │   └── date-utils/
│   │       ├── definition.json
│   │       └── date.xs
│   └── tables/
│       ├── user/
│       │   ├── definition.json
│       │   └── user.xs
│       └── session/
│           ├── definition.json
│           └── session.xs

Update Registry Configuration

JSON

{
   "$schema": "https://calycode.com/schemas/registry/registry.json",
   "name": "my-complete-registry",
   "description": "Complete set of reusable components",
   "items": [
      "items/auth/login/definition.json",
      "items/auth/register/definition.json",
      "items/auth/middleware/definition.json",
      "items/utils/string-helpers/definition.json",
      "items/utils/date-utils/definition.json",
      "items/tables/user/definition.json",
      "items/tables/session/definition.json"
   ]
}

Deployment Workflow

Local Development

Bash

# Terminal 1: Serve registry
caly-xano serve registry --path ./my-registry

# Terminal 2: Install components
caly-xano registry add auth/login \
  --registry http://localhost:5500/registry/definitions \
  --instance dev-instance \
  --workspace sandbox \
  --branch dev

Production Deployment

Bash

# Install from hosted registry
caly-xano registry add auth/login utils/string-helpers \
  --registry https://registry.mycompany.com/definitions \
  --instance production \
  --workspace main \
  --branch live

Install Multiple Components

Bash

# Space-separated list
caly-xano registry add tables/user tables/session auth/login auth/register \
  --registry http://localhost:5500/registry/definitions

Dependencies are automatically resolved and installed in the correct order.

Best Practices

1. Use Consistent Naming

Code

category/component-name

Good:
- auth/jwt-verify
- utils/string-helpers
- tables/user
- api/user-management

Bad:
- myFunction
- StringHelpers
- USER_TABLE

2. Document Everything

JSON

{
   "name": "auth/jwt-verify",
   "title": "JWT Token Verification",
   "description": "Verifies and decodes JWT tokens with RS256 or HS256 algorithms",
   "docs": "## Usage\n\nCall `jwt_verify(token)` with your token...",
   "postInstallHint": "Set XANO_JWT_SECRET or configure your RS256 public key"
}

3. Declare Dependencies Properly

JSON

{
   "name": "api/checkout",
   "registryDependencies": ["tables/order", "tables/product", "utils/stripe-client"]
}

4. Use Metadata for Versioning

JSON

{
   "meta": {
      "version": "1.2.0",
      "updated_at": "2024-01-15T10:30:00Z",
      "xano_version": "2.0+",
      "changelog": "Added support for refresh tokens"
   }
}

5. Test Before Sharing

Bash

# Always test in a development branch first
caly-xano registry add my-component \
  --registry http://localhost:5500/registry/definitions \
  --instance test \
  --workspace dev \
  --branch feature-test

Next Steps

Registry Authoring Guide - Complete registry documentation
XanoScript Guide - Working with XanoScript
Patterns & Best Practices - Common patterns for Xano development
Registry Add Command - CLI reference

Resources

XanoScript Docs: https://docs.xano.com/xanoscript/vs-code#usage
Registry Schema: https://calycode.com/schemas/registry/registry.json
Registry Item Schema: https://calycode.com/schemas/registry/registry-item.json
Discord Community: https://links.calycode.com/discord

Scaffolding New Xano Components

Table of Contents

Overview

Quick Start

Create a New Function Component

Scaffolding a Registry

The Scaffold Command

Generated Structure

Registry Configuration

Creating Component Definitions

Function Component

API Group Component

Table Component

Addon Component

Middleware Component

Task Component

Writing XanoScript

Getting Started

Recommended Development Setup

Example Workflow

Component Templates

Organizing Multiple Components

Update Registry Configuration

Deployment Workflow

Local Development

Production Deployment

Install Multiple Components

Best Practices

1. Use Consistent Naming

2. Document Everything

3. Declare Dependencies Properly

4. Use Metadata for Versioning

5. Test Before Sharing

Next Steps

Resources