Communitygithub.com

Neon Postgres (TanStack Start)

Integración de base de datos PostgreSQL con conmutación por error automática entre Neon (producción) y PGLite local (vista previa) para aplicaciones TanStack Start.

¿Qué es Neon Postgres (TanStack Start)?

Este skill integra una base de datos PostgreSQL en aplicaciones TanStack Start, con un modo de doble funcionamiento: cuando se despliega (con la variable `DATABASE_URL` configurada) utiliza **Neon Postgres** real, y en caso contrario (vista previa local o sandbox) recurre automáticamente a **PGLite** (Postgres embebido en WASM), de modo que la vista previa siempre funciona sin configuración adicional. La base de datos es **opt-in**: solo debe activarse cuando la aplicación necesita almacenar datos que sobreviven a la sesión del navegador o que se comparten entre dispositivos. El skill incluye un módulo `@/lib/db` que exporta `getSql()` (una función que devuelve un driver de Postgres estándar) y `dbSource`. Define el esquema en archivos SQL dentro de `migrations/`, que se aplican automáticamente tanto en Neon al desplegar como en PGLite al iniciar la vista previa. Soporta los comandos SQL mediante template literals etiquetados con tipado, y está diseñado para usarse exclusivamente en handlers del servidor (createServerFn). No debe usarse con datos personales sin autenticación de usuario; para eso se debe combinar con el skill de `auth`, que proporciona middleware para filtrar consultas por `userId`. Los paquetes necesarios (`pg` y `@electric-sql/pglite`) vienen preinstalados, no se deben instalar manualmente. No se debe crear un archivo `.env`: la variable `DATABASE_URL` se inyecta automáticamente por la plataforma al desplegar; en vista previa se deja sin configurar y se usa PGLite. La paridad entre vista previa y producción es alta, pero hay diferencias importantes (PGLite es en memoria, sin extensiones, sin bloqueos concurrentes; Neon tiene agrupación de conexiones sin estado de sesión). Recomienda usar columnas `user_id` de tipo `text` (no UUID) y evitar `bigint` más allá de 2^53. Para datos no autenticados (sin sign-in), las filas son de solo lectura/escritura mundial, por lo que nunca se deben almacenar datos personales o sensibles. El skill también incluye instrucciones detalladas sobre cómo activar la base de datos mediante el flag `deploy.database` en `.grok/app-env.json`.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/evalix098/tiktoklive/tree/HEAD/.grok/skills/neon

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Neon Postgres

La base de datos es optativa (AGENTS.md §0.5): úsala solo cuando la aplicación necesite datos que sobrevivan a una sesión del navegador o que se compartan entre dispositivos. De lo contrario, no incluyas migraciones, no importes @/lib/db y mantén el estado en localStorage / zustand.

Esta plantilla incluye una integración de base de datos de doble modo ya preparada:

  • Configurada (variable de entorno definida, ej. en despliegue): Neon Postgres real.
  • No configurada (vista previa en vivo del sandbox): la BD recurre a una PGLite local (Postgres WASM embebido), por lo que la vista previa siempre se renderiza. Desarrolla usando el ayudante @/lib/db; ambos modos funcionan con la misma API.

Los paquetes están preinstalados — no ejecutes npm install para ellos: pg (node-postgres, el controlador Postgres estándar) y @electric-sql/pglite (BD local de respaldo).

Para cuentas de usuario, inicio de sesión y lectura del usuario actual, consulta el skill auth aparte — este skill es solo la base de datos.

Activando la base de datos

Establece deploy.database a true en .grok/app-env.json:

{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }

Eso es lo que le indica a la plataforma que debe aprovisionar Neon para la aplicación desplegada; déjalo en false y el despliegue no tendrá DATABASE_URL, por lo que la aplicación se ejecutará silenciosamente sobre una PGLite desechable que perderá sus filas. Incluir archivos migrations/*.sql, o inicio de sesión, aprovisiona uno independientemente de esta bandera — esta bandera es para una aplicación que consulta @/lib/db sin ninguna de esas dos cosas. No es una clave VITE_ y nunca llega al navegador.

Variables de entorno — no crees un archivo .env

Nunca escribas un archivo .env / .env.local / .env.example para la base de datos. En la vista previa en vivo del sandbox, deja DATABASE_URL sin definir — @/lib/db usa automáticamente PGLite embebido. Cuando la aplicación se despliegue, la plataforma inyecta DATABASE_URL (Neon); tú no lo aprovisionas ni lo escribes.

VariableDóndePropósito
DATABASE_URLservidorCadena de conexión Neon cuando está desplegado (opcional — respaldo PGLite si no está definida)

Nunca la codifiques; nunca expongas variables que no sean VITE_ al cliente.

Base de datos (solo servidor)

@/lib/db exporta getSql() y dbSource: un controlador Postgres estándar (node-postgres, pg) contra DATABASE_URL, o un respaldo PGLite local cuando no está definida. La misma API en ambos casos — una plantilla etiquetada (y .query()) que resuelve a rows[]. Llámalo SOLO desde un manejador createServerFn / cargador de servidor, nunca desde un componente cliente. Define el esquema en migrations/, no en línea.

import { createServerFn } from "@tanstack/react-start";
import { getSql } from "@/lib/db";

export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
  const sql = await getSql();
  // Tipa la forma de la fila — el retorno de una función de servidor debe ser demostrablemente serializable.
  return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
  // o: return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
});

Datos por usuario (solo una vez que la aplicación tenga inicio de sesión). Un controlador regular tiene acceso completo a la BD, por lo que debes acotar cada consulta al usuario autenticado del lado del servidor — nunca confíes en un id enviado por el cliente. Usa el authMiddleware preconfigurado para obtener un context.userId verificado, luego filtra por él. El patrón completo (middleware, llamada desde código cliente, semántica de fallo cerrado) está en el skill auth:

import { authMiddleware } from "@/lib/auth/middleware";

export const listTodos = createServerFn({ method: "GET" })
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    const sql = await getSql();
    return sql<{ id: number; title: string }>`select id, title from todos where user_id = ${context.userId} order by id desc`;
  });
// las mutaciones también deben acotar escrituras: `... where id = ${id} and user_id = ${context.userId}`

Sin inicio de sesión (valor por defecto), NO uses authMiddleware / requireUserId. El usuario de desarrollo al que recurren es una conveniencia solo de vista previa. La variable VITE_AUTH_ENABLED de una aplicación desplegada es establecida por la plataforma, no por este espacio de trabajo (hoy el desplegador siempre la establece a "true"), por lo que al estar desplegada, ambos rechazan a cada visitante — y una aplicación sin autenticación no incluye ninguna ruta de inicio de sesión para que se recuperen. Una aplicación solo de base de datos mantiene sus filas sin dueño: sin columna user_id, o con una constante literal. Agrega el middleware como parte de activar el inicio de sesión (los pasos de actualización del skill auth), y re-acota o elimina esas filas entonces.

Las filas sin dueño son legibles y escribibles mundialmente a través de tus funciones de servidor públicas: nunca persistas datos personales o sensibles (nombres, correos electrónicos, texto libre sobre una persona) en este modo, y omite mutaciones destructivas masivas (eliminar todo, sobrescribir todo) — si la aplicación las necesita, propón en su lugar inicio de sesión.

Migraciones

Los archivos migrations/*.sql son la única fuente del esquema. Se aplican a Neon al desplegar (npm run build ejecuta db:migrate contra DATABASE_URL, por lo que Vercel se despliega con el esquema listo) y a la vista previa PGLite automáticamente al iniciar, por lo que desarrollo y producción coinciden.

Ningún aplicador desciende a subdirectorios, por lo que el esquema de Better Auth en migrations/auth/0001_auth.sql no se aplica a menos que la aplicación active el inicio de sesión y lo copie hacia arriba (no lo edites — consulta el skill auth). Coloca el esquema de tu aplicación en NUEVOS archivos ordenados a partir de 0002:

-- migrations/0002_schema.sql — ejemplo para una aplicación de tareas; usa LAS TABLAS de TU aplicación
create table if not exists todos (
  id         serial primary key,
  user_id    text not null,
  title      text not null,
  done       boolean not null default false,
  created_at timestamptz not null default now()
);
create index if not exists todos_user_id_idx on todos (user_id);

Nunca edites un archivo ya aplicado — se rastrea por nombre en _migrations y no se volverá a ejecutar (agrega un nuevo archivo en su lugar; los nuevos archivos se aplican a la vista previa en ejecución en la siguiente solicitud). Prefiere sentencias idempotentes (… if not exists). Las tablas con datos por usuario deben tener una columna user_id text not null (TEXT, no UUID — el id de usuario de desarrollo en vista previa es la cadena 'dev-user').

Paridad vista previa ↔ producción

getSql() normaliza los tipos de resultado para que ambos backend devuelvan formas idénticas y seguras para JSON: bigint/count(*) → number, date → cadena 'YYYY-MM-DD', interval → texto, numeric → cadena. Diferencias restantes a respetar:

  • bigint más allá de 2^53 pierde precisión como número — convierte con ::text si alguna vez necesitas enteros enormes (los recuentos de filas están bien).
  • La BD de vista previa está en memoria: se borra al reiniciar el servidor de desarrollo, es de una sola conexión (sin contención de bloqueos ni conflictos de escritura concurrente), y no carga extensiones — no uses create extension; quédate con Postgres básico.
  • El extremo agrupado de Neon no mantiene estado de sesión — no confíes en SET, LISTEN/NOTIFY, ni bloqueos de sesión con asesoramiento.
  • Mantén las columnas user_id como text — la vista previa usa 'dev-user', producción usa los ids de texto de Better Auth; una columna uuid rompe las inserciones en vista previa.
  • Las consultas a Neon desplegado atraviesan la red (y pueden reactivarse en frío) — evita patrones de consulta N+1 que se sientan gratuitos contra la BD de vista previa en proceso.

Individual skills in this repo

This repo contains 17 individual skills — each has its own dedicated page.

evalix098/tiktoklive

Add user accounts and sign-in to this TanStack Start app. Use when the app needs authentication, sign-in, user accounts, protected routes, or per-user data. Triggers on "auth", "login", "log in", "sign in", "sign up", "account", "users", "authentication", "protected", "who is logged in", "current user", "per-user".

evalix098/tiktoklive

Build browser games and interactive/canvas/3D experiences in this TanStack Start + React app. Use for any game, simulation, or WebGL/Canvas experience — 2D or 3D, single-player. Covers the game loop & timing, 3D orientation/camera conventions, collision, performance, assets, audio, save, game feel, and per-genre playbooks. For WASD / vehicle / flight **input signs and inverted A/D**, open the **`controls`** skill — do not rely on this file or racing-kart alone. Triggers on "game", "minecraft", "fps", "platformer", "racing", "tetris", "snake", "shooter", "3d", "three.js", "canvas", "voxel", "physics".

evalix098/tiktoklive

Player-facing input signs for browser games: WASD, vehicles, flight, FPS mouse-look, and the #1 failure mode (inverted A/D). Mandatory control self-tests and a tiny test interface so you can verify A turns left before shipping. Load for ANY game with movement, steering, flying, driving, tanks, boats, mechs, drones, planes, karts, third-person follow cams — not only racing. Triggers on "controls", "WASD", "inverted", "steer", "flight", "airplane", "kart", "vehicle", "yaw", "roll", "pitch", "mouse look", "A/D".

evalix098/tiktoklive

Design and build polished, non-generic UI for this TanStack Start + React + Tailwind v4 + shadcn/Radix app. Use whenever you create or restyle any interface surface — pages, landing pages, dashboards, forms, modals, nav, and game overlays (start screens, HUD, menus). Covers design tokens, layout, typography, color, spacing, motion, and the anti-"AI-slop" rules that keep output from looking generic. Triggers on "design", "UI", "make it look good", "polish", "landing page", "theme", "style", "redesign", "ugly", "clean up".

evalix098/tiktoklive

Deep guide for game ANIMATION assets: motion cycles, action keyframes, effect sequences, and animation sprite sheets — built around a video-first pipeline. In this app-builder sandbox, execute via the video2dsprite / generate2dsprite skills (magenta + scripts), not ad-hoc ffmpeg. Use whenever generating anything that moves: walk/run cycles, attacks, idles, FX, flags, fire, animation sheets. Complements game-asset-core.

evalix098/tiktoklive

Core discipline for ANY game-asset generation with Imagine tools: the engine-ready defaults users don't state, spec checklists, style anchoring, read-back verification, honest defect flagging. Use whenever generating any game art (sprites, sheets, animations, tiles, UI, FX) — then ALSO load the matching specialist skill: game-animation-frames for anything that moves, game-tilesets for tiles/terrain, game-character-consistency for recurring characters, game-ui-icons for UI and icons.

evalix098/tiktoklive

Deep guide for CHARACTER IDENTITY across images: turnarounds (front/side/ back), state and damage variants, palette swaps, equipment changes, and same-character-in-context sets. Use whenever generating character turnarounds, character sheets, variants of an existing sprite, or any same-subject multi-image set. Complements game-asset-core.

evalix098/tiktoklive

Deep guide for game TILE assets: seamless tileable textures, terrain transition tilesets, autotiles, and ground/platform tiles. Use whenever generating tileable textures, tilesets, terrain transitions, or seamless patterns. Complements game-asset-core.

evalix098/tiktoklive

Deep guide for game UI assets: buttons with interaction states, panels, bars, wordmark logos, and icon sets. Use whenever generating game UI elements, HUD assets, inventory icons, icon sets, buttons, or title logos. Complements game-asset-core.

evalix098/tiktoklive

Generate production-oriented 2D game maps with `imagine_text_to_image`: RPG/top-down maps, side-scroller parallax stages, tilemaps, layered raster maps, prop packs, collision zones, and walkable areas. Use when building browser games that need real map art (not pure code-drawn tiles), layered props, or map collision metadata. Triggers on "map", "level", "stage", "tilemap", "overworld", "dungeon", "side scroller background", "prop pack", "2D map".

evalix098/tiktoklive

Generate and postprocess 2D game sprites and animation sheets: pixel-art characters, NPCs, creatures, spells, projectiles, impacts, props, summons, and transparent PNG/GIF exports. Use when building browser games that need real sprite sheets (not code-drawn placeholders), matching a map art style, or producing magenta-background sheets for chroma-key cleanup. Triggers on "sprite", "sprite sheet", "animation sheet", "pixel art character", "walk cycle", "attack animation", "projectile sprite", "2D game asset".

evalix098/tiktoklive

How to use the Imagine tools in Grok Build: imagine_text_to_image, imagine_image_to_image, imagine_reference_to_image, imagine_text_to_video, imagine_image_to_video, imagine_reference_to_video, and render_file for chat previews. When to build a visual with code instead of generating it, prompt-craft, reference-first handling of real people, factual grounding, and asset-consistency. Load this whenever generating or editing an image or video is on the table. Tool-usage-driven, not triggered by a user merely mentioning images.

evalix098/tiktoklive

Peer-to-peer realtime multiplayer over WebRTC data channels: every user of the deployed app connects directly to every other user (full mesh), the server only brokers the handshake at /api/rtc. Lowest possible latency, zero per-message server cost. Use for 2-8 player co-op/casual realtime: shared cursors, drawing, party games, casual action. Triggers: p2p, peer to peer, webrtc, low latency multiplayer, direct connection.

evalix098/tiktoklive

Share-link previews and app identity for apps on *.grok.me: the injector-owned og:image card, the SVG favicon, and PWA icons for installable apps. Use when scaffolding, renaming, or restyling the app — and for share / unfurl / OG / Twitter card questions. A custom 1200×630 card from the app's own art is the default — games of every kind (DOM board/word games included), whimsical apps, creative tools, and brand-forward pages; only plain utilities keep the placeholder. Always run the brand-asset pass as a `task` subagent and never wait for it. Triggers on "share", "rename", "app name", "OG", "Open Graph", "twitter card", "unfurl", "og:image", "og:type", "x:game:image", "x-banner", "link preview", "social card", "thumbnail", "preview image", "favicon", "app icon", "PWA", "manifest", "installable", "home screen", "SEO", "meta description".

evalix098/tiktoklive

Official Three.js API and TSL (Three.js Shading Language) reference for LLM code generation. Load when writing or debugging three.js / WebGL / WebGPU / custom materials / shaders / GLTF / advanced three APIs beyond basic game loop/controls. Prefer building-games for game correctness (loop, WASD, camera, orientation); use this skill for full API/TSL depth. Triggers on "three.js", "threejs", "WebGPU", "TSL", "NodeMaterial", "shader", "GLTF", "MeshStandard", "OrbitControls", "WebGLRenderer".

evalix098/tiktoklive

Grok Build only. Turn a 2D character still into denser animation sprites via imagine_text_to_image base → imagine_image_to_video (6s/10s run-in-place) → ffmpeg frames → magenta chroma-key → dense sampled strips/grids/GIFs. Use when the user wants video-to-sprite, smoother run/walk cycles, or denser intermediate poses. Prefer generate2dsprite for crisp production pixel sheets. Triggers on "video to sprite", "imagine_image_to_video sprite", "dense walk cycle", "smooth run animation from video".

evalix098/tiktoklive

Call the xAI API (Grok) from this app's server code using the injected XAI_API_KEY: chat/LLM features, image and video generation (Imagine), and voice (text-to-speech). Use when the app needs any "AI" / "assistant" / "chatbot" / "Grok" functionality, runtime image/video generation, or speech. Triggers on "AI", "LLM", "chatbot", "assistant", "Grok", "xAI", "generate text", "summarize", "generate image", "AI video", "voice", "text to speech", "TTS", "OpenAI" (use xAI instead).

Skills relacionados