Getting Started

This guide walks you through creating a Notty CMS project, defining a content schema, and querying data via the REST API.

Prerequisites

• Node.js >= 20
• pnpm >= 9 (or npm/yarn)

1. Create a Project

npx @notty/create my-cms
cd my-cms

The scaffolder asks you to choose a starter template and a database.

Starter Templates

Template	What you get
default	Article schema — simple starting point
blog	Articles, categories, tags, authors + SEO
ecommerce	Products, categories, orders + SEO
portfolio	Projects, skills, testimonials, about page + SEO
minimal	No schemas — clean slate for your own model

You can also pass it directly:

npx @notty/create my-blog --template blog
npx @notty/create my-shop --template ecommerce --database postgresql

Database

The scaffolder asks you to choose a database:

Database	Best for
SQLite	Local development, prototyping
PostgreSQL	Production, high-traffic sites
MySQL/MariaDB	Existing MySQL infrastructure

The generated project structure:

my-cms/
  notty.config.ts    # Main configuration
  .env               # Environment variables
  schemas/           # Your content type definitions
  config/            # Project-level config fragments
  src/
    controllers/     # Reusable controller helpers
    hooks/           # App-local lifecycle hooks
    middlewares/     # Custom middleware
    plugins/app.ts   # App-level runtime plugin
    policies/        # App-local policies
    routes/          # Custom API routes
    services/        # App-local services
  public/            # Static assets
  data/              # SQLite database (dev)
  uploads/           # Created automatically on first local upload

2. Start the Server

pnpm dev

On the first boot, Notty creates a default super-admin automatically:

• Email: admin@notty.local
• Username: admin
• Password: admin123

Open http://localhost:2102/admin, sign in with one of those identifiers, and change the password immediately after the first login.

3. Create a Content Type

You can define schemas via the admin UI (Schema Builder) or as JSON files. Let's start with a JSON file.

Create schemas/article.json:

{
  "kind": "collectionType",
  "info": {
    "singularName": "article",
    "pluralName": "articles",
    "displayName": "Article",
    "description": "Blog articles"
  },
  "options": {
    "draftAndPublish": true,
    "timestamps": true
  },
  "attributes": {
    "title": {
      "type": "string",
      "required": true,
      "maxLength": 255
    },
    "slug": {
      "type": "string",
      "unique": true,
      "maxLength": 255
    },
    "body": {
      "type": "richtext"
    },
    "cover": {
      "type": "media",
      "allowedTypes": ["images"]
    },
    "category": {
      "type": "relation",
      "relation": "manyToOne",
      "target": "category"
    }
  }
}

Create schemas/category.json:

{
  "kind": "collectionType",
  "info": {
    "singularName": "category",
    "pluralName": "categories",
    "displayName": "Category"
  },
  "attributes": {
    "name": {
      "type": "string",
      "required": true,
      "unique": true
    },
    "description": {
      "type": "text"
    },
    "articles": {
      "type": "relation",
      "relation": "oneToMany",
      "target": "article",
      "mappedBy": "category"
    }
  }
}

Restart the server. Notty auto-syncs database tables from your schema files.

4. Authenticate

Get a JWT token:

curl -X POST http://localhost:2102/api/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "admin@notty.local",
    "password": "admin123"
  }'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGci...",
    "user": {
      "id": 1,
      "email": "admin@notty.local",
      "role": "super-admin"
    }
  }
}

Use the token in subsequent requests:

export TOKEN="eyJhbGci..."

5. Create Content

Create a category:

curl -X POST http://localhost:2102/api/content/category \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Technology", "description": "Tech articles" }'

Create an article:

curl -X POST http://localhost:2102/api/content/article \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello Notty",
    "slug": "hello-notty",
    "body": "<p>Welcome to Notty CMS!</p>",
    "category": 1
  }'

6. Query Content

List all articles

curl "http://localhost:2102/api/content/article" \
  -H "Authorization: Bearer $TOKEN"

Filter, sort and paginate

# Published articles, newest first, 10 per page
curl "http://localhost:2102/api/content/article?published=true&sort=created_at&sortOrder=desc&limit=10&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Populate relations

# Include category data in the response
curl "http://localhost:2102/api/content/article?populate=category" \
  -H "Authorization: Bearer $TOKEN"

Full-text search

curl "http://localhost:2102/api/content/article?search=notty&searchFields=title,body" \
  -H "Authorization: Bearer $TOKEN"

Advanced filters

# Articles with "hello" in the title
curl "http://localhost:2102/api/content/article?filters[title][\$contains]=hello" \
  -H "Authorization: Bearer $TOKEN"

7. Publish Content

New entries are drafts by default (when draftAndPublish is enabled). Publish an entry:

curl -X PUT http://localhost:2102/api/content/article/1/publish \
  -H "Authorization: Bearer $TOKEN"

8. Open the Admin Panel

Navigate to http://localhost:2102/admin. From here you can:

• Content Manager — create and edit entries with a form builder
• Schema Builder — add fields, relations, and components visually
• Media Library — upload and organize files
• Settings — configure site name, localization, security

Next Steps

• Content Modeling — all field types, relations, components
• Auth & Security — roles, permissions, API tokens
• Draft & Publish — publishing workflow and revisions
• Deployment — production-ready configuration