0.1.723 • Published 10h agoCLI

ugly-app

Licence

—

Version

0.1.723

Deps

Size

11.1 MB

Vulns

Weekly

12.2K

Summary Dependency Versions

ugly-app

A full-stack TypeScript framework for shipping production web apps with one CLI. Scaffold with npx ugly-app init my-app and get an opinionated Express + React + PostgreSQL stack with built-in auth, type-safe RPC over WebSocket and HTTP, real-time document tracking, AI generation, storage, and a CLI for every workflow.

ugly-app is designed to be deployed and operated through ugly.bot — the platform handles auth, infra (PostgreSQL, Qdrant, NATS, S3-compatible object storage), AI provider keys, and deployment. Your app talks to all of this through the project's dev tunnel and the per-app UGLY_BOT_TOKEN.

What's included

Server: Express + WebSocket with type-safe RPC and Zod validation
Client: React + Vite with typed routing, lazy pages, animated transitions, popup management
Database: PostgreSQL (JSONB) via the data proxy, with full-text search (search) and vector search (Qdrant vector)
Auth: HttpOnly cookies + JWT, ugly.bot OAuth out of the box, extensible via AuthProvider
AI: Text, image, embeddings, web search — all proxied through ugly.bot (no per-provider keys in your app)
Realtime: NATS pub/sub and document change subscriptions (trackDoc / trackDocs)
Storage: S3-compatible buckets with presigned uploads
Workers & cron: setWorkers() registers named async tasks with optional Zod input schemas and cron schedules
Localization: Strings tables with critical-string SSR injection
Experiments: Deterministic A/B bucketing tied to event logging
CLI: ugly-app commands for dev, build, deploy, migrations, logs, AI, and auth

Quick start

npx ugly-app init my-app
cd my-app
npm run dev

The scaffold gives you a working app at http://localhost:4321 with todo CRUD, AI chat, file upload, auth demo, collab editing, and ~20 other test pages wired up.

Server

`createApp()`

The single server entry point. Returns an App that owns Express, the WebSocket server, the typed DB, and the RPC dispatcher.

import {
  createApp,
  type AppConfigurator,
  type RequestHandlers,
} from 'ugly-app';
import { dbDefaults } from 'ugly-app/shared';
import { requests, messages } from '../shared/api';
import { collections } from '../shared/collections';
import { pages } from '../shared/pages';

const app = createApp(
  { requests, messages },
  {
    createTodo: async (userId, { text }) => {
      const _id = crypto.randomUUID();
      await app.db.setDoc(collections.todo, { _id, userId, text, done: false, ...dbDefaults() });
      return { id: _id };
    },
  } satisfies RequestHandlers<typeof requests>,
  collections,
  (configurator: AppConfigurator) => {
    configurator.setPages({ pages });
  },
);

await app.start(parseInt(process.env['PORT'] ?? '4321'));

Signature:

function createApp<R extends AppRegistryBase, Defs extends CollectionDefRegistry>(
  registry: R,                                       // { requests, messages }
  requests: Partial<RequestHandlers<R['requests']>>, // handler implementations
  appDefs: Defs,                                     // collections from defineCollections()
  configure?: (c: AppConfigurator) => void,
  deleteHandlers?: DeleteHandlers<Defs>,             // per-collection onDelete hooks
): App<CollectionMap<typeof BUILTIN_DEFS & Defs>>;

The returned App object has:

start(port?) — start the server (default port 3000; templates use 4321)
db — the TypedDB instance, also available globally via imports
httpServer — the underlying Node http.Server
wss — the main WebSocketServer (path set by setWsPath, default /rpc)
dispatch(name, input, userId) — invoke an RPC handler programmatically
registerRoutes(fn) — mount more Express routes after creation

Framework-managed background services start automatically: schema drift check, NATS connection + KV buckets (TTS, RATELIMIT), data-proxy connection, event counter flush, TTL cleanup for log tables, console / error capture, and ugly.bot log forwarding.

`AppConfigurator`

Passed to the optional fourth argument of createApp. Every method is optional.

Method	Description
`setPages({ pages, renderPage?, clientDistPath? })`	Mount the SPA. In dev, runs Vite in middleware mode; in prod, serves `dist/client`. Provide `renderPage` for SSR on pages with `ssr: true`.
`setUserHelper(helper)`	Customize how the framework reads / writes the `user` collection during WebSocket auth (default looks up by id in a generic `user` collection).
`setOnUserCreate(handler)`	Called on first login with `(userId, { email?, phone? }, db)` — your chance to create the user record.
`setAuth(provider)`	Replace the default ugly.bot OAuth provider. Must implement `verify(code)` and `authUrl(origin)`.
`setOnSocketMessage(handler)`	Single raw-WebSocket message handler. Return `true` to consume, `false` to fall through.
`addSocketMessageHandler(handler)`	Append to the handler chain; first to return `true` wins.
`setWsPath(path)`	Override the WebSocket path (default `/rpc`).
`setOnWsAuth(handler)`	`(ws, userId, req) => void` — fires after a socket session authenticates.
`setOnAfterStart(handler)`	`(db) => Promise<void>` — called once after data-proxy + NATS are ready.
`setOnMinuteTick(fn)` / `setOnHourlyTick(fn)`	Framework-managed periodic callbacks. Only fire when `CLOCK_ENABLED=true`.
`setHealthHandler(fn)`	Override the default `GET /health` response.
`setExperiments(experiments)`	Register `Experiment` definitions for `initSession` / `captureEvent` bucketing.
`setOnEmail(handler)`	Handle inbound emails routed to `{domain}@ugly.bot` (called via internal HTTP).
`setCronTasks(tasks, handlers)`	Legacy cron-only registry. Prefer `setWorkers()`.
`setWorkers(workers, handlers)`	Register named async tasks with optional Zod input schema and cron schedule. Powers `/_workers/manifest`, `POST /_workers/run`, and the cron orchestrator.
`setStrings(config)`	Localization config — framework injects language + critical strings into SSR HTML and exposes `resolveLanguage` / `getCriticalStrings`.
`registerRoutes(fn)`	Mount custom Express routes.
`setWorkerQueue(queue)`	Register a `WorkerQueue` with `start()` / `stop()` for app lifecycle management.

Handler signatures

Handlers are plain async functions — no context object:

// req() — public, userId may be null
getPublicData: async (userId: string | null, input) => { ... }

// authReq() — authenticated, framework returns 401 if no/invalid token
getMe: async (userId: string, input) => { ... }

Inside a handler, access state via captured imports — app.db, storage, pgQuery, uglyBotRequest, etc. There is no injected context.

Built-in framework requests

createApp automatically registers several framework handlers, accessible from any client via the normal RPC pipeline:

Name	Purpose
`userGet`	Returns `{ userId, name, avatarUri }` for the given user (or caller).
`initSession`	Records a session start, returns experiment branch assignments.
`captureEvent`	Records a client event tied to the session and experiment branches.
`textGen` / `imageGen`	AI proxies — server-validated, billed through ugly.bot.
`kagiSearch` / `kagiSummarize` / `kagiEnrichWeb` / `kagiEnrichNews`	Web search via ugly.bot.
`uploadUrl`	Issues a presigned PUT for the `temp` bucket.
`submitFeedbackBot`	Forwards `db.captureFeedback` writes for the maintain-bot persona.

App-provided handlers with the same name override the framework's defaults.

Shared API definitions

shared/ is consumed by both server and client. Keep all Zod schemas, types, collections, and route declarations here.

Requests (`shared/api.ts`)

import { authReq, defineRequests, req, z } from 'ugly-app/shared';

export const requests = defineRequests({
  // Public — handler signature: (userId: string | null, input) => Promise<output>
  getPublicData: req({
    input: z.object({ id: z.string() }),
    output: z.object({ data: z.string() }),
  }),

  // Authenticated — 401 enforced automatically, userId guaranteed string
  getMe: authReq({
    input: z.object({}),
    output: z.object({ userId: z.string(), email: z.string().optional() }),
  }),

  // With per-endpoint rate limiting (enforced before handler runs)
  submitFeedback: authReq({
    input: z.object({ type: z.enum(['bug', 'design', 'feature']), message: z.string() }),
    output: z.object({ id: z.string() }),
    rateLimit: { max: 20, window: 60 },
  }),
});

Every request is reachable as both socket.request(name, input) (WebSocket) and POST /api/:name { input } (HTTP). z is re-exported from Zod for convenience.

Collections (`shared/collections.ts`)

import { defineCollections, InferDocType } from 'ugly-app/shared';
import { z } from 'zod';

export const TodoSchema = z.object({
  userId: z.string(),
  text: z.string(),
  done: z.boolean(),
});
export type Todo = InferDocType<typeof TodoSchema>;

export const collections = defineCollections({
  todo: {
    schema: TodoSchema,
    meta: { cache: true, trackable: true, public: false, cascadeFrom: null },
  },
});

CollectionMeta:

cache — read getDoc through an LRU cache; writes invalidate it.
trackable — enables real-time trackDoc / trackDocs via NATS.
public — allow unauthenticated client reads.
cascadeFrom — parent collection for cascade deletes.
trackKeys? — fields usable as NATS routing keys for trackDocs.
search?: { fields, language? } — PostgreSQL full-text search columns.
vector?: { dimensions, source } — Qdrant vector index over the named JSONB path.

All documents extend DBObject: { _id, version, created, updated }. Use dbDefaults() to stamp the latter three on inserts.

After schema changes, run npm run db:schema-gen and then npm run db:migrate. The app refuses to start when drift is detected (set SCHEMA_CHECK_SKIP=true only as a last resort).

Pages (`shared/pages.ts`)

import { definePage, definePages } from 'ugly-app/shared';

export const pages = definePages({
  '':              definePage<{}>({ auth: false }),             // /
  'user/:userId':  definePage<{ userId: string }>(),            // /user/abc
  'search':        definePage<{ q?: string }>({ auth: false }), // /search?q=foo
  'blog/*slug':    definePage<{ slug: string }>({ ssr: true }), // /blog/any/path
});
export type AppPages = typeof pages;

:param matches a single path segment; *param is greedy (captures slashes).
The generic on definePage<Params>() is phantom — never set at runtime, used for client-side type inference.
auth defaults to true. ssr defaults to false.
Query-string params are declared in Params but never appear in the path template.

Client

`bootstrapApp()`

The recommended entrypoint. Handles auth detection, socket creation, silent auto-login through the ugly.bot iframe (Mode A only), and provider wiring.

// client/main.tsx
import { bootstrapApp, FeedbackButton } from 'ugly-app/client';
import { requests } from '../shared/api';
import { RouterProvider, RouterView } from './router';
import './styles.css';

bootstrapApp({
  requests,
  RouterProvider,
  render: () => (
    <>
      <RouterView />
      <FeedbackButton />
    </>
  ),
  strings: { /* optional StringsProviderConfig */ },
});

BootstrapAppOptions:

Field	Description
`requests`	Your `RequestRegistry` (merged with framework requests internally).
`messages?`	Your `MessageRegistry` (merged with framework messages).
`RouterProvider`	The `RouterProvider` returned from `createRouter()`.
`render`	Callback returning the app's UI tree (typically `<RouterView /> + <FeedbackButton />`).
`root?`	Root element / selector (default `'#root'`).
`fallback?`	UI for unmatched routes (default: tiny "404").
`socketUrl?`	Override the WebSocket path (default `/rpc`).
`strings?`	Localization config — when present, wraps the tree with `<StringsProvider>`.
`keyboard?: false`	Disable the framework `<KeyboardProvider>` wrapper.

bootstrapApp reads window.__AUTH_TOKEN__ (injected by the server). If absent, it renders unauthenticated and lets the router's per-route auth guard surface the framework's <AuthRoot> (Mode A → <LoginPopup>; Mode B → magic-link form + optional Google button). If the token is present, it connects the socket, mounts <AppProvider>, and renders.

If bootstrapApp is loaded at /auth/magic-link/verify (Mode B), it renders the <MagicLinkCallback> component instead of the regular app shell — that path is the fallback target when the server route is shadowed by a static-assets handler.

Routing — `createRouter()`

// client/router.ts
import { createRouter } from 'ugly-app/client';
import { pages } from '../shared/pages';
import { allPages } from './allPages';

export const { RouterProvider, RouterView, useRouter } = createRouter({
  pages,
  allPages,
});

createRouter returns:

RouterProvider — props: children, fallback?, isAuthenticated?. Manages route state, browser history, popups, and the silent auto-login iframe (<AutoLoginGate> — only in Mode A; skipped when window.__UGLY_APP_AUTH_MODE__ === 'self'). When isAuthenticated() returns false and the current route declares auth: true, the framework's <AuthRoot> is rendered in place of the page — apps cannot override this fallback.
RouterView — renders the active page with animated transitions. Props: durationMs?, easing?, transitionComponent? (replaces ViewFlipper), renderPage? (sync alternative to allPages loaders, called with RouterStateRaw).
useRouter() — returns the router context (see below).

Page map — `lazyPage` / `lazyPageLoader`

// client/allPages.ts
import { lazyPage, lazyPageLoader } from 'ugly-app/client';
import type { PageMap } from 'ugly-app/shared';
import type { AppPages } from '../shared/pages';

export const allPages = {
  ['']:             lazyPage(() => import('./pages/HomePage')),
  ['user/:userId']: lazyPage(() => import('./pages/UserPage')),
  ['slow/:id']:     lazyPageLoader(() => import('./pages/SlowPageLoader')),
} satisfies PageMap<AppPages>;

lazyPage(factory) — lazy-imports a default-exported React.ComponentType<Params>. The page receives route params as props.
lazyPageLoader(factory) — lazy-imports an async loader (params) => Promise<ReactElement>. Use when a route needs data fetching before render. The loader file is the chunk boundary, so it can statically import its page component.

Example loader:

// pages/SlowPageLoader.tsx
import SlowPage from './SlowPage';
export default async function PageLoader({ id }: { id: string }) {
  const data = await fetchSlowData(id);
  return <SlowPage {...data} />;
}

const { current, push, replace, back, openPopup, closePopup, closeAllPopups } = useRouter();

push('user/:userId', { userId: '123' });   // → /user/123
replace('search', { q: 'hello' });         // → /search?q=hello
back();                                     // browser history back

current.routeName; // typed union of all route keys
current.params;    // typed params for the current route

All route names and params are fully typed against pages. Internally push / replace are no-ops when buildUrl() produces a URL that doesn't match a registered route (and emit a console.error).

Popups — `openPopup()`

Always use useRouter().openPopup() for modals, sheets, and menus. The router owns the popup layer, manages the spring animation, and stacks popups z-index-correctly.

const { openPopup } = useRouter();

const handle = openPopup(<MyContent />, {
  mode: 'transient',    // 'block' (default) | 'transient' | 'contextMenu'
  slideFrom: 'bottom',  // 'left' | 'right' | 'top' | 'bottom' | 'none' (default)
  onClose: () => {},
  containerStyle: { /* CSS for the content wrapper */ },
  backgroundStyle: { /* CSS for the backdrop */ },
  animConfig: { duration: 300, easing: myEasingFn },
  renderLayer: (props) => <CustomLayer {...props} />, // fully replace the layer renderer
});

handle.hide(); // dismiss programmatically

Modes:

block (default) — 40% opacity backdrop, does not dismiss on backdrop click.
transient — 20% opacity backdrop, dismisses on backdrop click.
contextMenu — same as transient, intended for menus and pickers.

renderLayer receives { content, spring, hide } — spring is an AnimatedValueRef driving 0 → 1, hide closes the popup.

`AppProvider` & `useApp()`

bootstrapApp mounts <AppProvider> automatically after socket connect. Use useApp() inside any page to access the active user and socket.

const {
  userId,        // current user id
  user,          // UserBase doc
  socket,        // AppSocket — typed RPC client
  uglyBotSocket, // optional UglyBotSocket for direct platform calls (STT/TTS, etc.)
  showPopup,     // legacy popup API (prefer useRouter().openPopup)
  hidePopup,
  hideAllPopups,
  runAsync,      // runAsync(label, async () => { ... }, options?) — shows loading overlay while pending
  splashDone,    // mark a splash-screen step complete
  localizer,     // (key, params?) => string — alias for useLocalizer
} = useApp();

useApp is generic in TAsyncOptions so apps can pass an option type through to a custom loadingOverlay element. useAppOptional() returns null outside the provider; useLocalizer() returns a localizer that prefers <StringsProvider> data, falls back to the AppProvider localizer prop, and finally to identity.

`Link` component

import { Link } from 'ugly-app/client';

<Link router={router} to="user/:userId" params={{ userId: '123' }}>View profile</Link>

Renders an <a> with the right href, intercepts clicks for client-side navigation, and lets ctrl/cmd+click open in a new tab.

Direct socket access

AppSocket is exposed through useApp().socket. Common methods:

Method	Description
`request(name, input)`	Invoke a typed RPC handler.
`getDoc(collection, id)`	Server-mediated doc fetch.
`getDocs(collection, filter?, opts?)`	Filtered query.
`trackDoc(collection, id, cb)`	Live subscription — returns unsubscribe.
`trackDocs(collection, params, cb)`	Live filtered subscription.
`uploadFile(file, key)`	Presigned upload to the `temp` bucket.
`connectionState`	`'connecting' \| 'connected' \| 'reconnecting' \| 'disconnected' \| 'idle-disconnected'`.
`disconnect()`	Close the connection.

For pure HTTP (no WebSocket), use createHttpClient({ requests, token?, baseUrl? }).

Auth

ugly-app uses HttpOnly cookies and server-side JWT injection — no localStorage, no client-side token handling.

Two modes, picked from the auth block in the project's .uglyapp config:

Mode A — mode: 'uglybot' (default when no auth block is present). Auth is delegated to ugly.bot OAuth. AI / email / push proxies bill the end user's ugly.bot credits.
Mode B — mode: 'self'. The app issues its own sessions via magic-link email and/or Google OAuth. AI / email / push proxies bill the developer's ugly.bot account using the project's AI_PROXY_TOKEN.

window.__UGLY_APP_AUTH_MODE__ is injected into every page so client code (incl. <AuthRoot> and the router's <AutoLoginGate>) can branch correctly.

Mode A — ugly.bot OAuth (default)

Unauthenticated user lands on a page. The router's <AutoLoginGate> opens a hidden iframe to ${UGLY_BOT_URL}/iframe-auth to check for an existing platform session (4 s timeout).
If found, the iframe postMessages an OAuth code back. The client POSTs to /auth/verify; the server exchanges it through uglyBotAuthProvider, sets the auth_token HttpOnly cookie, and reloads.
If not found (or timeout), per-route auth checks surface the framework's <AuthRoot> → <LoginPopup>, which opens ${UGLY_BOT_URL}/oauth in a popup window.
On every authenticated page request, the server verifies the cookie token by calling ${UGLY_BOT_URL}/verify, then injects window.__AUTH_TOKEN__ into the HTML so the client can attach it to the WebSocket handshake.

Mode B — Self-issued sessions

When .uglyapp sets auth.mode: 'self', buildAuth() wires the magic-link provider as primary; if providers.google.clientId is configured it adds Google as an extra provider on the same router.

<AuthRoot> renders <MagicLinkForm> (plus the Google button when configured) instead of <LoginPopup>.
The <AutoLoginGate> is skipped entirely — the ugly.bot iframe would either silently fail or set a cookie that won't verify against the local session.
POST /auth/magic-link/request accepts an email, mints a one-time token (default 15 min lifetime, configurable via auth.magicLinkExpiresMin), and emails a link.
GET /auth/magic-link/verify?token=… validates the token, calls onUserCreate on first login, sets the session cookie, and redirects.
Google login lives at GET /auth/google/url + POST /auth/google/callback when enabled.

Token-in-URL embed

Any GET request with ?token=<JWT> will, if the token verifies, set the cookie and 302-redirect to the same URL without the token parameter — useful for embedding any page in an iframe.

Built-in routes

Mounted on every app:

Endpoint	Description
`POST /auth/verify`	Exchange an OAuth `code` for a session cookie.
`POST /auth/logout`	Clear the cookie.
`GET /auth/token`	Refresh and return the current token.
`GET /auth/url`	Return the OAuth popup URL.
`POST /auth/magic-link/request`	Mode B only — send a magic-link email.
`GET /auth/magic-link/verify`	Mode B only — verify a magic-link token and set the cookie.
`GET /auth/google/url`, `POST /auth/google/callback`	Mode B only — Google OAuth, registered when configured.

Custom provider

configurator.setAuth({
  verify: async (code) => ({ userId: '...', token: 'platform-issued-jwt' }),
  authUrl: (origin) => `https://my-oauth.example/authorize?origin=${origin}`,
  registerRoutes: (router, { db, onUserCreate }) => { /* extra routes */ },
});

Server-side helpers (`ugly-app`)

verifyToken(token) — verifies a token against ugly.bot and returns the userId.
getRequestUser(req) — synchronous decode of the per-project UGLY_PROJECT_TOKEN cookie set by ugly.bot's wake-on-traffic gate. Returns { userId } | null without a network round-trip; safe to use as the primary auth check in deployed-app handlers.

Database — `TypedDB`

Access via app.db or via import { app } from './your-app-module'. All methods accept a CollectionDef (from defineCollections) or a plain collection name string.

Writing

await db.setDoc(collections.note, doc);                                  // upsert
await db.setDoc(collections.note, doc, { skipIfExists: true });          // insert-only

await db.setDocFields(collections.note, id, { title: 'New' });           // partial; throws if missing
await db.setDocFieldsOrIgnore(collections.note, id, { title });          // returns null if missing
await db.setDocFieldsOrCreate(collections.note, id, { title }, default); // upsert with default

await db.setDocOp(collections.note, id, { $inc: { views: 1 } });         // MongoDB-style ops
await db.setDocOpOrIgnore(collections.note, id, { $inc: { views: 1 } });

Supported update operators: $inc, $addToSet, $pull, $unset, $set. All keys are dot-notation, fully typed against the collection's schema.

Reading

const doc  = await db.getDoc(collections.note, id);
const docs = await db.getDocs(collections.note, { userId }, { sort: { created: -1 }, limit: 20 });

// Typed SQL-native query API (preferred for new code)
const notes = await db.find(collections.note, { userId, done: { $ne: true } }, { sort: { created: -1 }, limit: 20 });
const count = await db.findCount(collections.note, { userId });
const sample = await db.findRandom(collections.note, { userId }, 5);

// Aggregation pipelines (legacy / advanced)
const results = await db.getQuery<MyResult>('note', pipeline, { skip, limit });
const total   = await db.getQueryCount('note', pipeline);

// Dynamic / untyped access — when the collection name is a runtime string
await db.rawGetDoc('note', id);
await db.rawGetDocs('note', filter);

Deleting

await db.deleteDoc(collections.note, id);                  // cascade-deletes children
await db.deleteWhere(collections.note, { userId });        // typed bulk delete
await db.deleteQuery(collections.note, { userId });        // legacy untyped bulk delete

Pass deleteHandlers as the 5th argument to createApp to run per-collection onDelete callbacks.

Search

// Full-text search — requires `search: { fields, language? }` on the collection
const hits = await db.searchDocs(collections.note, 'react hooks', { limit: 10 });

// Vector search — requires `vector: { dimensions, source }` (uses Qdrant)
const similar = await db.vectorSearch(collections.note, embeddingVector, { limit: 10 });

Caching

db.cacheGet<MyType>(key);
db.cacheSet(key, value, ttlMs);
db.cacheDelete(key);                                       // broadcasts invalidation via NATS
const k = db.cacheKey('prefix', id);

Helpers

import { createUserHelper, dbDefaults } from 'ugly-app';

const newDoc = { _id: crypto.randomUUID(), ...dbDefaults(), title: 'Hi' };
//                                          ^^^^^^^^^^^^^^^ { version: 1, created, updated }

const userHelper = createUserHelper<User>(collections.user);
const user = await userHelper.get(db, userId);

Direct SQL & infra

Imports available from ugly-app:

pgQuery(sql, params?) — parameterized SQL on the data proxy.
ensureTable(...), tableExists(...), ensureSearchColumn(...).
ensureQdrantCollection(...), upsertVector(...), searchVectors(...), deleteVector(...), deleteQdrantCollection(...).
connectNats(), natsPublish(subject, payload), natsSubscribe(subject, cb), ensureKvBucket(name, opts), jsPublish(...), jsConsumerCreate(...), jsConsumerConsume(...).
subscribeCollection, subscribeDoc, subscribeDocKey — NATS subjects emitted by the data proxy on writes.

AI

AI calls are proxied through ugly.bot — your app never holds an AI provider key. Pass UGLY_BOT_TOKEN in the environment and the framework handles routing, balance tracking, retries, and per-user billing.

Server-side text generation

import { createTextGenClient } from 'ugly-app';
const textGen = createTextGenClient(userId);

const text = await textGen.generate(messages, { model: 'gemini_2_5_flash' });

Or call the framework textGen request directly:

import { uglyBotRequest } from 'ugly-app';
const { message } = await uglyBotRequest<{ message: { content: string } }>('textGen', {
  model: 'gemini_2_5_flash',
  messages: [{ role: 'user', content: 'Hello!' }],
  options: { maxTokens: 512 },
});

Available models are exposed via textGenModels / textGenModelData from ugly-app — the platform supports Claude, GPT, Gemini, Together, Groq, Fireworks, and Kie families.

Server-side image generation

import { createImageGenClient } from 'ugly-app';
const imageGen = createImageGenClient(userId);

const url = await imageGen.generate('A red panda eating noodles', { model: 'flux_schnell' });

imageGenModels / imageGenModelData enumerate available models (Together FLUX, FAL, Google Imagen, Wavespeed, Kie Kolors).

Embeddings

import { createEmbeddingClient, cosineSimilarity } from 'ugly-app';
const embeddings = createEmbeddingClient();
const vector = await embeddings.embed('hello world');
const sim = cosineSimilarity(vectorA, vectorB);

Web search

import { createWebSearchClient } from 'ugly-app';
const search = createWebSearchClient(userId);

await search.search({ query: 'react 19', limit: 10 });
await search.summarize({ url: 'https://...' });
await search.enrichWeb({ query: 'topic' });
await search.enrichNews({ query: 'topic' });

Client-side AI calls

Calls from React components go through the framework RPC pipeline — no token plumbing in the browser:

import { callTextGen, callJsonGen, callImageGen } from 'ugly-app/client';

const text  = await callTextGen({ messages, model: 'gemini_2_5_flash' });
const json  = await callJsonGen({ messages, schema, model: 'gemini_2_5_flash' });
const image = await callImageGen({ prompt: 'a corgi astronaut', model: 'flux_schnell' });

STT / TTS

Speech goes directly from the browser to ugly.bot — never proxied through your app server.

import { useSTT, useTTS, AudioPlayer, AudioRecorder } from 'ugly-app/client';

const { start, stop, transcript, isListening } = useSTT(socket, options);
const { speak, stop: stopTTS } = useTTS(socket, { voice: 'alloy' });

Storage

S3-compatible. Two logical buckets:

temp — short-lived uploads (presigned PUT from the browser).
public — durable, served by CDN.

Server-side:

import { createStorageClient } from 'ugly-app';
const storage = createStorageClient();

await storage.put('temp', key, buffer, 'image/png');
const publicUrl = await storage.moveToPublic(tempKey, destKey);
const url = storage.url('public', destKey);
const { uploadUrl, resultUrl } = await storage.presignedPut('temp', key);

Client-side, use socket.uploadFile(file, key) — it requests a presigned URL via the built-in uploadUrl framework request and streams the upload. In dev, uploads go through a same-origin /_s3 proxy to avoid CORS with local MinIO.

STORAGE_KEY_PREFIX (env) prefixes all keys — useful for per-environment isolation.

Workers & cron

// shared/cron.ts
import { defineWorkers, z } from 'ugly-app/shared';

export const cronTasks = defineWorkers({
  dailyCleanup: {
    schedule: '0 3 * * *',   // every day at 03:00 UTC
    description: 'Delete completed todos older than 30 days',
  },
  resyncSearch: {
    inputSchema: z.object({ since: z.string().datetime() }),
    description: 'Re-embed search vectors since the given ISO timestamp',
  },
});

// server/index.ts
const cronHandlers: WorkerHandlers<typeof cronTasks> = {
  dailyCleanup: async () => { /* runs on schedule */ },
  resyncSearch: async ({ since }) => { /* runs on manual trigger from studio */ },
};

configurator.setWorkers(cronTasks, cronHandlers);

Each worker can have inputSchema, outputSchema, schedule, timeout, description. Workers without a schedule are still invocable via POST /_workers/run (auth: localhost in dev, Authorization: Bearer $CRON_SECRET in prod). Scheduled workers also appear in /_cron/manifest for the deploy orchestrator.

Localization

configurator.setStrings({
  defaultLang: 'en',
  langs: ['en', 'es'],
  criticalKeys: ['app.title', 'nav.home'],
  getTable: (lang) => tables[lang] ?? tables.en,
});

The framework injects window.__LANG__, window.__STRINGS_VERSION__, and window.__CRITICAL_STRINGS__ into SSR HTML. Use useLocalizer() / useStrings() / useLang() / useChangeLanguage() on the client.

Experiments

import type { Experiment } from 'ugly-app/shared';

export const experiments: Experiment[] = [
  {
    id: 'new-onboarding',
    name: 'New Onboarding',
    active: true,
    branches: [
      { id: 'control', weight: 50 },
      { id: 'variant', weight: 50 },
    ],
    events: ['ONBOARDING_COMPLETE'],
  },
];

configurator.setExperiments(experiments);

Bucketing is deterministic: hash(experimentId + userId) (or sessionId for unauthenticated users). The framework's initSession / captureEvent requests automatically tag events with the user's branch assignments.

Built-in endpoints

Endpoint	Description
`GET /health`	Health check — returns `{ status, timestamp, lastRequestAt }`.
`POST /api/:name`	Dispatch any registered request handler over HTTP.
`POST /auth/verify`	Exchange OAuth code for session cookie.
`POST /auth/logout`	Clear the auth cookie.
`GET /auth/token`	Refresh and return the current token.
`GET /auth/url`	Get the OAuth popup URL.
`GET /_workers/manifest`	Worker definitions (used by ugly-studio).
`POST /_workers/run`	Synchronously invoke a worker handler.
`GET /_workers/runs`	Recent in-memory worker runs (last 200).
`GET /_cron/manifest`	Cron tasks for the deploy orchestrator.
`POST /api/_cron/:taskName`	Trigger a cron task (auth via `CRON_SECRET`).
`POST /internal/email-callback`	Inbound email gateway (auth via `INTERNAL_EMAIL_SECRET`).
`PUT /_s3/*`	Dev-only S3 upload proxy (avoids CORS with MinIO).

Package entry points

Import path	Description
`ugly-app`	Server: `createApp`, `TypedDB`, auth, AI clients, NATS, storage, email, push, workers.
`ugly-app/shared`	Cross-tier: `defineRequests`, `defineCollections`, `definePage`, `defineWorkers`, Zod, experiments, time constants.
`ugly-app/client`	React: `bootstrapApp`, `createRouter`, `lazyPage`, `AppProvider`, components, animations, audio, AI helpers.
`ugly-app/conversation/{shared,server,client}`	AI chat sessions with persisted history.
`ugly-app/collab/{server,client}`	Yjs-based collaborative editing.
`ugly-app/markdown/{shared,client}`	Markdown rendering + editor.
`ugly-app/webrtc`, `ugly-app/webrtc/server`	WebRTC video rooms.
`ugly-app/three/{server,client}`	Three.js scene helpers.
`ugly-app/worker`	Worker queue runtime.
`ugly-app/playwright`	Test utilities.
`ugly-app/vite`, `ugly-app/eslint`	Build-tool plugins.

Environment variables

Variable	Description
`PORT`	Server port (templates default to 4321).
`NODE_ENV`	`development` or `production`.
`UGLY_BOT_TOKEN`	App token for the ugly.bot platform — required for AI, logs, billing.
`UGLY_BOT_URL`	Override the platform base URL (default `https://ugly.bot`).
`DATA_PROXY_URL`	WebSocket URL for the data proxy (default `ws://localhost:4200`).
`DATA_PROXY_TOKEN`	Auth token for the data proxy.
`STORAGE_KEY_PREFIX`	Prefix all storage keys (per-env isolation).
`MINIO_ENDPOINT`	Dev-only S3 endpoint for the upload proxy.
`NATS_PREFIX` / `COMPOSE_PROJECT_NAME`	NATS subject prefix for per-env isolation.
`CLOCK_ENABLED`	`true` to enable `setOnMinuteTick` / `setOnHourlyTick`.
`CRON_SECRET`	Bearer secret for `POST /api/_cron/:taskName` and prod `POST /_workers/run`.
`MAINTAIN_BOT_USER_ID`	User id allowed to access admin-only handlers.
`INTERNAL_EMAIL_SECRET`	Shared secret for `/internal/email-callback`.
`JWT_SECRET`	Required when using `getRequestUser()` for the per-project session cookie.
`APP_DOMAIN`	App domain; combined with `NATS_PREFIX` for `getRequestUser()` validation.
`LOG_CAPTURE_URL`	Studio override for client log capture (empty → ugly.bot default).
`UGLY_APP_HMR`	Set to `false` to disable Vite HMR in dev.
`SCHEMA_CHECK_SKIP`	`true` to start despite schema drift (unsafe).

Browser-visible variables must be prefixed VITE_ and consumed via import.meta.env.VITE_*.

CLI

Command	Description
`ugly-app init <name>`	Scaffold a new project.
`ugly-app upgrade`	Upgrade framework config files to the latest version.
`ugly-app configure`	Generate/update `.uglyapp` config.
`ugly-app login`	Authenticate with ugly.bot.
`ugly-app url`	Print the local dev server URL.
`ugly-app deploy`	Build + push to production infrastructure.
`ugly-app prod --buildId <id>`	Promote a build to prod.
`ugly-app versions`	List deployed versions.
`ugly-app versions:prune`	Clean up non-prod versions.
`ugly-app infra:destroy`	Tear down all project infra.
`ugly-app textGen [prompt]`	Generate text via AI (`--model`, `--system-prompt`, `--max-tokens`, `--json`).
`ugly-app imageGen [prompt]`	Generate an image (`--model`, `--output <path>`).
`ugly-app error:dev` / `error:prod`	Query error logs (your tunnel / production).
`ugly-app perf:dev` / `perf:prod`	Query performance metrics.
`ugly-app feedback:dev` / `feedback:prod`	Query user feedback.
`ugly-app feedback:submit` / `feedback:resolve`	Manage feedback (run with `--help` for flags).

Inside a scaffolded project, the same commands are available via npm run … scripts — see templates/CLAUDE.md for the full list.

Migrations

Schema changes must be deliberate:

Update the Zod schema in shared/collections.ts.
Run npm run db:schema-gen — produces a migration file with compile-blocking REPLACE_ME placeholders for any non-trivial change.
Replace every REPLACE_ME with the correct migration logic.
Run npm run db:migrate.

The framework refuses to start when drift is detected (set SCHEMA_CHECK_SKIP=true only as a temporary escape hatch).

Tech stack

Node.js · TypeScript · Express · React 19 · Vite · PostgreSQL (JSONB) · Qdrant · NATS · S3-compatible storage · Zod · JWT (jose) · ugly.bot platform