Hasyx

Hasyx = Next.js + Hasura + auth + client + building

Hasyx provides a robust starting point and a set of tools for building applications using Next.js (App Router), Hasura, and strong authentication patterns. It simplifies setup with JWT-based authentication via NextAuth.js, a secure GraphQL proxy to Hasura, direct WebSocket support for subscriptions, and a powerful dynamic query generator.

Technologies Used

Hasyx takes responsibility for:

• Setting up a universal, ssr/server/ws/serverless/client compatible Next.js environment.
• Proxying client connections to Hasura through /api/graphql, eliminating the need to expose Hasura JWTs to the client and relying solely on NextAuth.js for authorization.
• Providing access via both the native ApolloClient and a custom Hasyx class for interacting with Hasura, is super easy syntax sugar for the most common queries, mutations and subscriptions.
  • const hasyx = useClient() hook for easy client access.
  • hasyx.insert/update/delete/select/subscribe for easy data manipulation.
  • useQuery/useSubscription hooks for easy data fetching and subscribing from react.
• A fully configured NextAuth.js integration supporting multiple authentication methods (including Credentials, Google, Yandex, with others like GitHub planned).
• Maintaining backward compatibility for UI components under hasyx/components/ui/* (generated via shadcn/ui) to minimize refactoring needs in downstream projects.
• Ensuring seamless compatibility between Vercel deployments and Hasura Cloud/Server.
• Structuring the ./lib/** directory so its contents can be directly imported as if from an npm package, allowing the project to function as both a standalone application and a reusable library accessable from application by package.json name import { anything } from 'you-project-name'; anywhere.
• Standardizing resource identification using Hasyx Identifiers (HID).
• Pre-configuring Jest for TypeScript testing of files within the ./lib directory.
• Integrating Resend for sending email verification messages (when RESEND_API_KEY is set).
• Interactive npx hasyx cli js [<filePath>] [-e "<script>" | --eval "<script>"] for quick scripting, data exploration, or debugging interactions with your Hasura backend, with the client object available in the global scope.
• Event-Driven AI Engine: A modular AI core built around a Dialog orchestrator. It supports tool usage and multiple LLM backends through a provider pattern (Ollama for local models, OpenRouter for cloud models). Interaction is primarily handled via the npm run ask command-line interface. See AI.md for architecture details.
• Universal Code Execution Engine: A secure JavaScript/TypeScript execution environment.
• Terminal Emulation Library: A library for spawning and managing shell processes.
• Migrations control with npx hasyx migrate [filter] and npx hasyx unmigrate [filter] for easy database schema management from ./migrations directory, with optional filtering to run only specific migrations.
• Event triggers with npx hasyx events for easy event trigger management from ./events directory, already configured to NEXT_PUBLIC_MAIN_URL (vercel in most cases) /api/events/[name] routing with security headers.
• Server-side Debug Logging: Built-in debug() method for database logging when HASYX_DEBUG=1 is enabled, storing structured debug data in a dedicated debug table for monitoring and troubleshooting production systems.
• Progressive Web App (PWA) Support: Complete PWA functionality with service workers, offline support, installability, and push notifications. See PWA.md for details.
• Audit Trail & Logs System: Comprehensive audit trail functionality with configurable database triggers for tracking granular string changes (using diff-match-patch) and complete state snapshots. Features include CLI management with npx hasyx logs, JSON-based configuration via hasyx.config.json, selective column tracking, and complete Hasura permissions integration. See LOGS.md for details.
• GitHub → Telegram Bot Integration: Automated CI/CD notifications via Telegram bot with AI-generated commit summaries, strict status reporting, and privacy-focused messaging. Features strict workflow status reporting (PASSED/FAILED for tests, builds, deploys), privacy-focused messaging (no author names), smart MD file linking, and rich English-language notifications. Waits for all workflows to complete, then sends detailed messages with commit analysis, test results, deployment URLs, and direct links to repository and documentation. Uses a modular architecture: github-telegram-bot-hasyx.ts (core functionality with generator function) и github-telegram-bot.ts (проектная конфигурация). Конфигурируется переменной HASYX_GITHUB_TELEGRAM_BOT. См. TELEGRAM_BOT.md.
• Capacitor Integration: Cross-platform application building (Android, iOS, Desktop, Browser Extensions, etc.) with automated build workflows using Fastlane. See FASTLANE.md for complete mobile build automation.
• Cytoscape Integration: A powerful set of React components for graph visualizations using Cytoscape.js, allowing for custom HTML rendering within nodes and reactive style updates. See CYTO.md for details.
• DNS and SSL Management: Comprehensive subdomain management with automated HTTPS setup using CloudFlare DNS, Let's Encrypt SSL certificates, and nginx configuration. Features include DNS propagation waiting, automatic certificate renewal, idempotent operations, and complete subdomain lifecycle management. Configure CloudFlare API credentials and domain settings via hasyx.config.json (keys: HASYX_DNS_DOMAIN, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, LETSENCRYPT_EMAIL). See CLOUDFLARE.md, SSL.md, NGINX.md, and SUBDOMAIN.md for details.
• URL Query State Management: A powerful use-query hook for synchronizing state between multiple components using URL query parameters. Features automatic URL synchronization, multi-component state sharing, TypeScript support, browser navigation compatibility, SSR safety, and JSON serialization for complex objects. Perfect for search pages, filters, pagination, and any scenario where you need shareable, bookmarkable URLs with persistent state. See USE-QUERY.md for complete documentation and examples.
• Docker Hub Publishing: Automated Docker image building and publishing via GitHub Actions with configurable publishing control. Features multi-architecture support (AMD64/ARM64), optimized Dockerfile with multi-stage builds. Configure DOCKERHUB_USERNAME/DOCKERHUB_PASSWORD via hasyx.config.json. See DOCKER.md for complete documentation and setup instructions.

Applying best development practices from the listed ecosystems, we have combined these libraries into a single framework for rapid deployment.

Detailed Documentation

Explore the different modules and functionalities of Hasyx:

• AI.md: High-level overview of the event-driven AI architecture.
• ASK.md: Guide to using the AI command-line interface.
• OLLAMA.md: Instructions for using local models with Ollama.
• OPENROUTER.md: Instructions for using cloud models with OpenRouter.
• GENERATOR.md: Learn about the powerful dynamic query generator for Hasura.
• CONSTRUCTOR.md: Visual GraphQL query builder with real-time results and development roadmap.
• APOLLO.md: Understand how to use the Apollo Client with Hasyx.
• AUTH.md: Details on authentication helpers and NextAuth.js integration.
• HASURA.md: Information about the Hasura admin client and its usage.
• HASYX.md: Documentation for the core Hasyx client class and its features.
• GRAPHQL-PROXY.md: How the secure GraphQL proxy to Hasura works.
• EXEC.md: Universal JavaScript code execution engine for both Node.js and browser environments.
• EXEC-TS.md: TypeScript execution engine with in-memory compilation and automatic configuration loading.
• TERMINAL.md: Comprehensive terminal emulation library for Node.js with process spawning, command execution, session management, and factory functions for different terminal types.
• MARKDOWN-TERMINAL.md: Beautiful markdown formatting for terminal output with colors, syntax highlighting, and proper styling.
• CYTO.md: Guide to Cytoscape.js integration for graph visualizations.
• HID.md: Explanation of Hasyx Identifiers (HID) for resource identification.
• EVENTS.md: Complete guide to Hasura Event Triggers integration with automatic synchronization and secure webhook handling.
• SCHEDULE.md: Comprehensive documentation for the Schedule system with cron-based event planning, real-time processing, and database integration.
• PWA.md: Progressive Web App support with offline functionality, installability, and push notifications.
• LOGS.md: Comprehensive audit trail system with granular diff tracking and complete state snapshots for your Hasura database.
• MESSAGING.md: Messaging schema and permission model (rooms, messages, replies) with streaming subscriptions and read cursors.
• GROUPS.md: Groups schema and permission model (groups, memberships, invitations) with triggers and allow-lists.
• NOTIFY.md: Overview of the notifications system.
• NOTIFY-FIREBASE.md: Specifics on Firebase Cloud Messaging for push notifications.
• NOTIFY-TELEGRAM-BOT.md: Details on Telegram Bot integration for notifications.
• TELEGRAM_BOT.md: GitHub Actions → Telegram Bot integration for automated CI/CD notifications with AI-generated commit summaries, strict status reporting, and privacy-focused messaging.
• TBANK.md: Documentation for TBank payments integration.
• TINKOFF_API.md: Base documentation for Tinkoff API interactions.
• CLOUDFLARE.md: Documentation for CloudFlare DNS management.
• SSL.md: Documentation for SSL certificate management.
• NGINX.md: Documentation for Nginx configuration.
• SUBDOMAIN.md: Documentation for subdomain management.
• DOCKER.md: Complete Docker containerization guide with automated Hub publishing, multi-architecture builds, and interactive configuration tools.
• USE-QUERY.md: Complete guide to URL query state management with the use-query hook for synchronizing state between multiple components through URL parameters.
• FILES.md: Complete guide to Hasyx Files Storage system with S3-compatible storage, file upload/download, metadata management, and REST API integration.
• PLV8.md: Complete guide to plv8 (PostgreSQL JavaScript) extension support for creating JavaScript functions and triggers in PostgreSQL with cross-platform compatibility.
• FASTLANE.md: Complete guide to Fastlane integration for automated mobile app building, signing, and deployment with CI/CD integration.
• GEO.md: PostGIS-powered geospatial layer (schema geo, features table, spatial helpers, permissions) with Hasyx client usage examples.

🚀 Quick Start

Get your Next.js project integrated with Hasura and authentication in minutes!

1. Install Hasyx:

   npm install hasyx
   # or
   yarn add hasyx
   # or
   pnpm add hasyx

2. Initialize Hasyx: Run the init command in your project root. This will set up necessary API routes, configurations, and patch your Next.js project for WebSocket support.

   npx hasyx init

   See the init command documentation below for details on created files.

   If you need to reinstall and replace ALL files, including those that normally wouldn't be overwritten, use:

   npx hasyx init --reinit

3. Configure via Hasyx Config (do not edit .env manually): Run the configurator to edit hasyx.config.json. The .env and docker-compose.yml files are auto-generated and must not be edited by hand.

   npx hasyx config
   # or non-interactive generation:
   npx hasyx config --silent

   Notes:

   • The generated .env includes a header: “This file is auto-generated by hasyx config. DO NOT EDIT MANUALLY.”
   • Always change settings through hasyx.config.json using npx hasyx config.

4. Setup Database & Schema:

   • Create your database tables and relationships using the Hasura class. You can adapt the example migrations in the hasyx package under migrations/hasyx/ (up.ts, down.ts). Place your migration scripts in a migrations/<your_migration_name>/ directory in your project root. Use define* methods for idempotent operations.
   • Apply migrations: npx hasyx migrate
   • Generate Hasura schema JSON and TypeScript types: npx hasyx schema
   • 📖 For comprehensive migration guidelines and patterns, see CONTRIBUTING.md - Writing Database Migrations.

5. Easy configure ColorMode, Session and Apollo with HasyxProvider: Wrap your application layout (e.g., app/layout.tsx) with the Apollo Provider.

   'use client'; // Layout must be client-side due to providers
   
   import { HasyxProvider } from "hasyx";
   import "./globals.css";
   
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <>
         <html lang="en" suppressHydrationWarning>
           <head />
           <body>
             <HasyxProvider>
               {children}
             </HasyxProvider>
           </body>
         </html>
       </>
     )
   }

6. Use Hasyx Client for Data: Fetch, mutate, and subscribe to your Hasura data using Hasyx hooks and the Client class, which leverage a powerful query generator.

   import { useClient, useQuery, useSubscription } from 'hasyx';
   
   function MyComponent() {
     // Get the Hasyx client instance
     const client = useClient();
   
     // Fetch users
     const { data: usersData, loading: usersLoading, error: usersError } = useQuery({
       table: 'users',
       returning: ['id', 'name', 'email'],
       where: { name: { _ilike: '%a%' } },
       limit: 10,
     });
   
     // Subscribe to user changes (using the hook)
     const { data: subData, loading: subLoading } = useSubscription({
       table: 'users',
       returning: ['id', 'name'],
       limit: 5,
       order_by: { created_at: 'desc' }
     });
   
     return <>
       <div onClick={async () => {
         const result = await client.insert({
           table: 'users',
           // Generator syntax for variables is used directly in client methods
           objects: [{ name: 'New User', email: 'new@example.com' }],
           returning: ['id'] // Return the ID of the new user
         });
         // Similarly, you can use:
         // await client.update({ table: 'users', where: { id: { _eq: userId } }, _set: { name: 'Updated Name' } });
         // await client.delete({ table: 'users', where: { id: { _eq: userId } } });
         // await client.select({ table: 'posts', returning: ['id', 'title'] });
       }}>
       <div>
         {subData.map(user => <div key={user.id}>{user.name}</div>)}
       </div>
     </>;
     // ... render your component using the fetched/subscribed data ...
   }

   Refer to GENERATOR.md and HASYX.md for detailed syntax.

7. Run Development Server:

   npx hasyx dev

8. Use the AI Assistant: Start interacting with the AI using the ask command.

   # Get help on a topic using the default cloud provider
   npm run ask -- -e "How do I add a new table in Hasura?"
   
   # Use a local model via Ollama
   npm run ask -- -e "Write a python script to parse a CSV file" --provider ollama --model codellama:7b

⚙️ CLI Commands

Hasyx provides a CLI tool (run via npx hasyx <command>) to simplify common tasks:

🔧 CLI Extensibility in Child Projects

When you install Hasyx as a dependency in your project, you can extend the CLI with your own custom commands while keeping all the base Hasyx functionality. This is achieved through a template-based approach:

How it works:

1. Hasyx provides a base CLI with all standard commands (dev, build, migrate, assets, etc.)
2. Child projects can create their own CLI that extends the base functionality
3. The child project's CLI automatically inherits all Hasyx commands
4. You can add custom commands specific to your project

Setting up CLI in your child project:

1. Copy the CLI template (done automatically during npx hasyx init):

   # The template is copied to your project as lib/cli.ts
   # It imports and extends the base Hasyx CLI functionality

2. Add your package to npm scripts in your package.json:

   {
     "name": "your-project-name",
     "bin": {
       "your-project-name": "./lib/cli.js"
     },
     "scripts": {
       "build": "NODE_ENV=production npx -y hasyx build",
       "unbuild": "npx -y hasyx unbuild",
       "start": "NODE_ENV=production npx -y hasyx start",
       "dev": "npx -y hasyx dev",
       "ws": "npx --yes next-ws-cli@latest patch -y",
       "postinstall": "npm run ws -- -y",
       "migrate": "npx hasyx migrate",
       "unmigrate": "npx hasyx unmigrate",
       "tsx": "npx hasyx tsx",
       "ask": "NODE_OPTIONS=\"--experimental-vm-modules\" tsx lib/ask.ts"
     }
   }

3. Build and use your CLI:

   npm run build:lib
   npx your-project-name --help  # Shows all Hasyx commands + your custom ones
   npx your-project-name dev     # Same as npx hasyx dev
   npx your-project-name assets  # Same as npx hasyx assets

Adding custom commands: You can extend the CLI by modifying your lib/cli.ts file to add project-specific commands while keeping all base Hasyx functionality.

Benefits:

• ✅ Keep all Hasyx commands (dev, build, migrate, assets, etc.)
• ✅ Add your own project-specific commands
• ✅ Consistent CLI experience across projects
• ✅ Easy distribution via npm packages
• ✅ Automatic environment variable loading from .env

---

config

Interactive project configuration and silent artifacts generation.

# Interactive UI (Ink-based). Edits hasyx.config.json and auto-updates .env and docker-compose.yml on changes
npx hasyx config

# Silent mode: only generate .env and docker-compose.yml and exit (no UI)
npx hasyx config --silent

# Equivalent npm script provided in this repo for development
npm run config

What it does (authoritative source of truth):

• Reads/writes hasyx.config.json
• Generates .env via lib/config/env.tsx
• Generates docker-compose.yml via lib/config/docker-compose.tsx

Important:

• .env and docker-compose.yml are marked as auto-generated. Do not edit them manually.
• Use npx hasyx config to change any environment settings. The tool writes to hasyx.config.json and regenerates artifacts.

Tip: Use --silent in CI to re-generate artifacts without interactive UI.

---

init

Initializes Hasyx in your Next.js project. It copies necessary API routes, configuration files, and applies the next-ws patch for WebSocket support.

npx hasyx init

You can also use the --reinit flag to force replacement of all files, including those that would normally only be created if they don't exist:

npx hasyx init --reinit

File Operations:

• 🔄 = Overwrites the file if it exists.
• ✨ = Creates the file only if it does not exist (or always replaces it with --reinit).

Note: Files marked with ✨ are "soft copied" - they won't overwrite existing files unless you use --reinit or --force. This is particularly useful for files like public/hasura-schema.json that you may have already generated and customized in your project.

npm Scripts Setup:

During initialization, Hasyx ensures that the following npm scripts are added to your project's package.json:

"scripts": {
  "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --verbose --runInBand",
  "build": "NODE_ENV=production npx -y hasyx build",
  "unbuild": "npx -y hasyx unbuild",
  "start": "NODE_ENV=production NODE_OPTIONS=\"--experimental-vm-modules\" npx -y hasyx start",
  "dev": "NODE_OPTIONS=\"--experimental-vm-modules\" npx -y hasyx dev",
  "doc:build": "NODE_OPTIONS=\"--experimental-vm-modules\" npx hasyx doc",
  "ws": "npx --yes next-ws-cli@latest patch -y",
  "postinstall": "npm run ws -- -y",
  "migrate": "npx hasyx migrate",
  "unmigrate": "npx hasyx unmigrate",
  "events": "NODE_OPTIONS=\"--experimental-vm-modules\" npx hasyx events",
  "schema": "npx hasyx schema",
  "npm-publish": "npm run build && npm publish",
  "cli": "NODE_OPTIONS=\"--experimental-vm-modules\" npx hasyx",
  
  "js": "NODE_OPTIONS=\"--experimental-vm-modules\" npx hasyx js",
  "logs": "npx hasyx logs",
  "logs-diffs": "npx hasyx logs-diffs",
  "logs-states": "npx hasyx logs-states"
}

These scripts allow you to use standard npm commands (e.g., npm run dev, npm run build) in your project while leveraging Hasyx's enhanced functionality. The scripts automatically use the Hasyx CLI and apply the necessary environment variables.

WebSocket Support:

When running init, Hasyx automatically patches your Next.js project for WebSocket support:

.
|-- 🔄 CONTRIBUTING.md
├── .github/
│   └── workflows/
│       └── 🔄 workflow.yml      # Unified CI/CD workflow for tests, builds, deployments, and releases
├── app/
│   ├── ✨ sidebar.ts
│   ├── ✨ layout.tsx
│   ├── ✨ page.tsx
│   ├── ✨ globals.css
│   ├── 🔄 options.ts
│   └── api/
│       ├── events/
│       │   ├── [name]/
│       │   │   └── 🔄 route.ts     # Default event handler for Hasura
│       │   ├── subscription-billing/
│       │   │   └── 🔄 route.ts     # Subscription billing event handler
│       │   ├── notify/
│       │   │   └── 🔄 route.ts     # Notification event handler
│       │   ├── logs-diffs/
│       │   │   └── 🔄 route.ts     # Logs diff event handler
│       │   ├── github-issues/
│       │   │   └── 🔄 route.ts     # GitHub issues event handler for bidirectional sync
│       │   └── your-custom-event-handler/
│       │       └── ? route.ts      # Your custom event handlers (copy from [name]/route.ts)
│       ├── auth/
│       │   ├── 🔄 route.ts         # Auth API specific logic (if any)
│       │   ├── [...nextauth]/
│       │   │   └── 🔄 route.ts     # NextAuth.js main handler
│       │   ├── verify/
│       │   │   └── 🔄 route.ts     # Email verification or similar auth actions
│       │   ├── verify-telegram-webapp/
│       │   │   └── 🔄 route.ts     # Telegram WebApp authentication validation
│       │   └── get-jwt/
│       │       └── 🔄 route.ts     # JWT token generation endpoint
│       ├── github/
│       │   └── issues/
│       │       └── 🔄 route.ts     # GitHub issues API (GET, POST, PUT, PATCH for webhooks)
│       ├── graphql/
│       │   └── 🔄 route.ts         # Hasyx GraphQL Proxy to Hasura
│       ├── telegram_bot/
│       │   └── 🔄 route.ts         # Handler for Telegram Bot webhooks
│       └── health/
│           └── 🔄 route.ts         # Health check endpoint
├── components/
│   ├── sidebar/
│   │   └── ✨ layout.tsx        # Sidebar layout component
│   ├── entities/
│   │   └── ✨ default.tsx       # Default entity component
├── lib/
│   ├── ✨ entities.tsx          # Entity definitions (staged from _lib)
│   ├── ✨ ask.ts               # AI assistant integration (staged from _lib)
│   ├── ✨ debug.ts             # Debug utilities (staged from _lib)
│   ├── ✨ cli.ts               # CLI utilities (staged from _lib)
│   ├── ✨ github-telegram-bot.ts # GitHub→Telegram bot integration (staged from _lib)
├── migrations/
│   ├── 1746660891582-hasyx-users/
│   │   ├── ✨ up.ts
│   │   └── ✨ down.ts
│   ├── 1746670608552-hasyx-notify/
│   │   ├── ✨ up.ts
│   │   └── ✨ down.ts
│   ├── 1746837333136-hasyx-debug/
│   │   ├── ✨ up.ts
│   │   └── ✨ down.ts
│   ├── 1748511896530-hasyx-payments/
│   │   ├── ✨ up.ts
│   │   └── ✨ down.ts
│   ├── 1746999999999-hasyx-logs/
│   │   ├── ✨ up.ts
│   │   └── ✨ down.ts
│   └── 29991231235959999-hasyx/
│       ├── ✨ up.ts
│       └── ✨ down.ts
├── app/
│   ├── hasyx/
│   │   ├── diagnostics/
│   │   │   └── ✨ page.tsx      # Hasyx diagnostics page
│   │   ├── aframe/
│   │   │   ├── ✨ page.tsx      # A-Frame VR integration page
│   │   │   └── ✨ client.tsx    # A-Frame client component
│   │   ├── payments/
│   │   │   └── ✨ page.tsx      # Payments integration page
│   │   ├── cyto/
│   │   │   ├── ✨ page.tsx      # Cytoscape graph visualization page
│   │   │   └── ✨ client.tsx    # Cytoscape client component
│   │   ├── pwa/
│   │   │   ├── ✨ page.tsx      # PWA configuration page
│   │   │   └── ✨ client.tsx    # PWA client component
│   │   ├── constructor/
│   │   │   └── ✨ page.tsx      # Visual GraphQL query builder page
│   │   ├── validation/
│   │   │   └── ✨ page.tsx      # Form validation testing page
│   │   ├── files/
│   │   │   └── ✨ page.tsx      # Files management page
│   │   ├── messaging/
│   │   │   └── ✨ page.tsx      # Messaging interface page
│   │   ├── roadmap/
│   │   │   ├── ✨ page.tsx      # Development roadmap page
│   │   │   └── ✨ client.tsx    # Roadmap client component
│   │   ├── telegram-miniapp/
│   │   │   └── ✨ page.tsx      # Telegram Mini App page
│   │   └── doc/
│   │       ├── ✨ page.tsx      # Documentation index page
│   │       └── [filename]/
│   │           └── ✨ page.tsx  # Dynamic documentation page
|-- public/
│   ├── ✨ logo.svg             # Default logo, replace with your own
│   ├── ✨ favicon.ico           # Default favicon
│   └── ✨ hasura-schema.json   # Hasura GraphQL schema (soft copy, won't overwrite existing)
|-- events/
│   ├── ✨ notify.json           # Default Hasura event trigger definition for notifications
│   ├── ✨ schedule.json         # Default Hasura event trigger definition for schedule
│   ├── ✨ schedule-cron.json    # Default Hasura event trigger definition for schedule-cron
│   ├── ✨ subscription-billing.json # Default Hasura event trigger definition for subscription-billing
│   ├── ✨ logs-diffs.json       # Default Hasura event trigger definition for logs-diffs
│   └── ✨ github-issues.json    # GitHub issues event trigger for bidirectional sync
├── .vscode/
│   └── ✨ extensions.json       # Recommended VS Code extensions
├── ✨ .gitignore               # Git ignore patterns (from _lib/.gitignore)
├── ✨ .npmignore               # NPM ignore patterns (from _lib/.npmignore)
├── ✨ .npmrc                   # NPM configuration (from _lib/.npmrc)
├── ✨ Dockerfile               # Docker container configuration
├── ✨ Dockerfile.postgres      # PostgreSQL Docker container with PLV8 and PostGIS
├── ✨ .dockerignore            # Docker ignore patterns
├── ✨ vercel.json              # Vercel deployment configuration
├── ✨ babel.jest.config.mjs    # Babel configuration for Jest
├── ✨ jest.config.mjs          # Jest testing configuration
├── ✨ jest.setup.js            # Jest setup file
├── ✨ next.config.ts           # Next.js configuration
├── ✨ postcss.config.mjs       # PostCSS configuration
├── ✨ components.json          # shadcn/ui configuration
├── ✨ tsconfig.json            # TypeScript configuration
└── ✨ tsconfig.lib.json        # TypeScript library configuration

Note: GitHub workflow files and CONTRIBUTING.md are copied as examples and might need adjustment for your specific repository.

---

dev

Starts the Next.js development server (next dev).

npx hasyx dev

---

build

Builds your Next.js application for production (next build).

npx hasyx build

---

start

Starts the Next.js production server (next start). Requires a previous build.

npx hasyx start

---

migrate

Finds and executes up.ts migration scripts located in subdirectories of ./migrations (e.g., ./migrations/001_users/up.ts, ./migrations/002_posts/up.ts) in alphabetical order of the subdirectories.

npx hasyx migrate

Filter Migrations: You can optionally provide a filter to run only migrations containing a specific substring in their directory name:

# Run only migrations with "users" in directory name
npx hasyx migrate users

# Run only migrations with "auth" in directory name  
npx hasyx migrate auth

# Examples:
# migrations/1746660891582-hasyx-users/ ✅ matches "users"
# migrations/1746670608552-hasyx-notify/ ❌ doesn't match "users"
# migrations/1748511896530-hasyx-payments/ ❌ doesn't match "users"

Important for Writing Migrations: When writing migration scripts, use the Hasura class from hasyx/lib/hasura for consistent and reliable schema management. Always prefer define* methods over create* methods to ensure idempotency - migrations can be run multiple times without causing errors.

Quick Example:

// migrations/001_example/up.ts
import { Hasura, ColumnType } from 'hasyx/lib/hasura';

export default async function up() {
  const hasura = new Hasura({
    url: process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL!,
    secret: process.env.HASURA_ADMIN_SECRET!
  });

  await hasura.defineSchema({ schema: 'public' });
  await hasura.defineTable({ schema: 'public', table: 'users' });
  await hasura.defineColumn({
    schema: 'public',
    table: 'users',
    name: 'email',
    type: ColumnType.TEXT,
    unique: true
  });
}

📖 For comprehensive migration guidelines, patterns, and best practices, see CONTRIBUTING.md - Writing Database Migrations.

---

unmigrate

Finds and executes down.ts migration scripts located in subdirectories of ./migrations in reverse alphabetical order of the subdirectories.

npx hasyx unmigrate

Filter Migrations: You can optionally provide a filter to rollback only specific migrations containing a substring in their directory name:

# Rollback only migrations with "users" in directory name
npx hasyx unmigrate users

# Rollback only migrations with "auth" in directory name
npx hasyx unmigrate auth

# Examples:
# migrations/1746660891582-hasyx-users/ ✅ matches "users" 
# migrations/1746670608552-hasyx-notify/ ❌ doesn't match "users"
# migrations/1748511896530-hasyx-payments/ ❌ doesn't match "users"

It uses npx tsx to run the scripts. See migrations for an example.

---

schema

Generates the Hasura GraphQL schema and corresponding TypeScript types for use with the query generator and client hooks. It performs two steps:

1. Runs a script (internally lib/hasura-schema.ts) to fetch the introspection schema from your Hasura instance (NEXT_PUBLIC_HASURA_GRAPHQL_URL) and saves it to ./public/hasura-schema.json in your project.
2. Runs graphql-codegen using the configuration (internally lib/hasura-types.ts) to generate TypeScript definitions based on the fetched schema, saving them to ./types/hasura-types.d.ts in your project.

npx hasyx schema

Run this command whenever your Hasura database structure (tables, columns, relationships) changes.

---

events

Synchronize Hasura event triggers with local definitions

• Option: --init - Create default event trigger definitions
• Option: --clean - Remove security headers from event definitions (they will be added automatically during sync)

The CLI automatically loads environment variables from the .env file in your project root. This ensures that commands like npx hasyx events

---

Interactive Project Configuration Assistant

Interactive assistant to set up and configure your Hasyx project with step-by-step prompts for all major components.

# Run the full assistant (recommended for new projects)
npx hasyx

# Skip specific steps

🎯 Available Configuration Options:

Authentication & Security:

• --skip-auth - Skip GitHub authentication check
• --skip-secrets - Skip authentication secrets setup
• --skip-oauth - Skip OAuth configuration

Project Setup:

• --skip-repo - Skip repository setup
• --skip-env - Skip environment setup
• --skip-package - Skip package.json setup
• --skip-init - Skip hasyx initialization

Database & Backend:

• --skip-hasura - Skip Hasura configuration
• --skip-pg - Skip PostgreSQL configuration
• --skip-migrations - Skip migrations check

External Services:

• --skip-resend - Skip Resend configuration
• --skip-firebase - Skip Firebase configuration
• --skip-telegram - Skip Telegram Bot configuration
• --skip-openrouter - Skip OpenRouter API Key setup
• --skip-github - Skip GitHub Token setup
• --skip-github-webhooks - Skip GitHub webhooks configuration

Infrastructure:

• --skip-dns - Skip DNS configuration
• --skip-docker - Skip Docker configuration
• --skip-storage - Skip Storage configuration
• --skip-vercel - Skip Vercel setup

Development:

• --skip-sync - Skip environment variable sync
• --skip-commit - Skip commit step
• --skip-project-user - Skip setting up project user

✨ Assistant Features:

Interactive Configuration:

• Step-by-step setup with clear prompts
• Automatic environment variable management
• Base URL detection for OAuth callbacks
• Repository validation and formatting

GitHub Integration:

• GitHub OAuth app configuration
• Webhook setup for issues synchronization
• Automatic secret generation
• Repository owner/repo name parsing

Storage Configuration:

• Local MinIO setup
• Cloud storage providers (AWS S3, GCP, Azure, DigitalOcean, Cloudflare R2)
• Antivirus scanning (ClamAV)
• Image manipulation and optimization

Documentation Generation:

• Creates detailed setup instructions
• Generates configuration files
• Provides troubleshooting guides
• Updates environment variables

Example Workflows:

New Project Setup:

# Complete setup for a new project
npx hasyx

GitHub Webhooks Only:

# Configure only GitHub webhooks

Storage Configuration Only:

# Configure only storage

📖 See GITHUB-WEBHOOKS.md for detailed webhook setup instructions.

---

subdomain 🌐

Complete Subdomain Management with DNS, SSL, and Nginx

Manage DNS records, SSL certificates, and Nginx configurations for subdomains with automated HTTPS setup using CloudFlare DNS, Let's Encrypt SSL certificates, and nginx configuration.

# Show help with all subcommands and examples
npx hasyx subdomain --help

# List all DNS records for your domain
npx hasyx subdomain list

# Create subdomain with DNS record only
npx hasyx subdomain define app1 149.102.136.233

# Create full subdomain with DNS, SSL certificate, and Nginx configuration
npx hasyx subdomain define app1 149.102.136.233 3000

# Remove subdomain completely (DNS, SSL, and Nginx)
npx hasyx subdomain undefine app1

🎯 Available Subcommands:

• list - List all DNS records for the domain
• define <subdomain> <ip> [port] - Create subdomain with optional SSL and Nginx
• undefine <subdomain> - Remove subdomain completely

🔧 Requirements: The following environment variables are required:

• HASYX_DNS_DOMAIN (or DOMAIN) - Your domain name
• CLOUDFLARE_API_TOKEN - CloudFlare API token with Zone:Edit permissions
• CLOUDFLARE_ZONE_ID - CloudFlare Zone ID for your domain
• LETSENCRYPT_EMAIL (optional) - Email for SSL certificates

Configure these variables using:

npx hasyx

✨ Features:

• DNS Management: Automatic A record creation via CloudFlare API
• SSL Certificates: Let's Encrypt certificates with automatic renewal
• Nginx Configuration: Reverse proxy setup with HTTPS redirect
• DNS Propagation: Automatic waiting for DNS changes
• IP Validation: Built-in IP address format validation
• Idempotent Operations: Safe to run multiple times

Example Workflow:

# 1. List existing DNS records
npx hasyx subdomain list

# 2. Create a subdomain for your API server
npx hasyx subdomain define api 149.102.136.233 8080

# 3. Result: https://api.yourdomain.com → http://127.0.0.1:8080

See SUBDOMAIN.md for complete documentation, CLOUDFLARE.md for DNS management details, SSL.md for certificate management, and NGINX.md for web server configuration.

---

ask 🤖

AI Assistant with Real-time Progress Indicators

Interactive AI assistant powered by OpenRouter with automatic code execution capabilities. Features real-time progress indicators showing exactly what AI is doing step-by-step.

# Primary usage via npx hasyx:
npx hasyx ask -e "Calculate factorial of 5 using JavaScript"
npx hasyx ask -y -m "anthropic/claude-3-sonnet" -e "Question"

# Interactive chat mode
npx hasyx ask

# Alternative usage for development inside hasyx project:
npm run cli -- ask -e "Calculate factorial of 5 using JavaScript"
npm run cli -- ask -y -m "anthropic/claude-3-sonnet" -e "Question"

# Or using npm script (for projects with hasyx integration):
npm run ask -- -e "What is the capital of France?"

🎯 Command Options:

• -e, --eval <question> - Ask a direct question and get a response
• -y, --yes - Auto-approve code execution (no confirmation)
• -m, --model <model> - Specify OpenRouter model
• -h, --help - Show help information

🎯 Real-time Progress Features:

• 🧠 AI is thinking... - When AI is generating responses
• 💭 AI responded (N characters) - Response received with character count
• 📋 Found JS/TSX code to execute - Code found for execution
• ⚡ Executing JS/TSX code... - Code execution in progress
• ✅ Execution result - Execution results displayed

🔄 Automatic Code Execution:

• AI can execute JavaScript and TypeScript code automatically
• Results are fed back to AI for continued reasoning
• Up to 3 iterations for complex problem solving
• Supports both Node.js and browser environment APIs

Example Output:

$ npx hasyx ask -e "Check process.platform"

🧠 AI is thinking...
💭 AI responded (156 characters)
📋 Found JS code to execute:
```js
process.platform

⚡ Executing JS code... ✅ Execution result: darwin

🧠 AI is thinking... 💭 AI responded (298 characters)

You're running on macOS (darwin platform)...

**Requirements:**
- `OPENROUTER_API_KEY` environment variable
- Free DeepSeek model via OpenRouter API

See **[ASK.md](ASK.md)** for complete documentation and examples.