Primeros pasos

Aprende a configurar un proyecto de Carats y a poner en marcha una aplicación renderizada en el servidor.

Requisitos

Carats usa Bun para la gestión de paquetes y para ejecutar el servidor de desarrollo. Bun transpila TSX sobre la marcha, así que no hay un paso de compilación aparte durante el desarrollo. Node.js 20+ también sirve para compilaciones de producción, pero Bun es la vía con soporte.

Inicio rápido

La forma más rápida de empezar es el generador de proyectos oficial. Escribe una aplicación de Carats completa y funcional, con facetas, culets, un diseño compartido, tokens de diseño en SASS y pruebas, de modo que todas las funcionalidades descritas en esta documentación ya están conectadas y se pueden leer como código en funcionamiento.

Crear un proyecto nuevo

bun create carats my-carats-app
cd my-carats-app

`bun create carats` resuelve el paquete publicado `create-carats` y ejecuta su binario `create-carats`, que escribe un proyecto de Carats completo en el directorio que indiques. Si no pasas directorio, se genera en el actual.

Instalar dependencias e iniciar el servidor de desarrollo

bun install
bun run dev

El servidor escucha en `http://localhost:5173`. El proyecto generado incluye un panel, un mercado, una cartera, una página de operaciones, un diseño compartido, una página de no encontrado y una página de error, así que todas las funcionalidades descritas en esta documentación ya están conectadas y se pueden leer como código en funcionamiento.

Configuración manual

Si prefieres partir de un proyecto vacío, crea la estructura de carpetas siguiente e instala las dependencias tú mismo.

Estructura de carpetas

Crea las siguientes carpetas y archivos. Las ubicaciones son fijas porque el framework las resuelve por convención.

src/
├── app.ts
├── vite-env.d.ts
├── dto/
│   ├── user.d.ts
│   └── trade-data.d.ts
├── client/
│   ├── index.html
│   ├── entrypoint.ts
│   ├── facets.tsx
│   ├── base.sass
│   ├── components/
│   │   ├── SearchInput.tsx
│   │   └── search-bar.sass
│   └── pages/
│       ├── _layout/index.tsx
│       ├── _error/index.tsx
│       ├── _not_found/index.tsx
│       ├── home/index.tsx
│       ├── market/index.tsx
│       ├── profile/index.tsx
│       └── trade/index.tsx
└── server/
    ├── entrypoint.ts
    └── culets.ts
public/
vite.config.client.ts
vite.config.server.ts
vitest.config.ts
tsconfig.json
package.json

Instalar dependencias

Carats está dividido en paquetes pequeños. Las dependencias de ejecución que se muestran son las que usa una aplicación de pila completa; las de desarrollo hacen falta para la transpilación de JJSX, SASS y la comprobación de tipos.

Dependencias de ejecución

bun add @carats/core @carats/render @carats/hooks @carats/csr
bun add @carats/ssr @carats/express @carats/ssg
bun add express compression sirv

Dependencias de desarrollo

bun add -d jjsx vite sass typescript
bun add -d @types/node @types/express @types/compression
bun add -d vitest @vitest/coverage-v8 @fetch-mock/vitest cross-env

`@carats/express` requiere Express 5, por lo que la versión principal no es opcional.

Configuración

Configuración de TypeScript

Carats requiere un tsconfig.json en la raíz del proyecto. Las opciones types, jsx, jsxFactory y jsxFragmentFactory son las que enseñan a TypeScript qué es JJSX, y typeRoots es lo que hace resolubles las interfaces DTO globales de src/dto.

{
  "compilerOptions": {
    "target": "es2022",
    "useDefineForClassFields": true,
    "module": "esnext",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "types": ["jjsx"],
    "typeRoots": ["./src/dto", "./node_modules"],
    "skipLibCheck": true,
    "jsx": "react",
    "jsxFactory": "JJSX.jsxFactory",
    "jsxFragmentFactory": "JJSX.fragmentFactory",

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["src"]
}

`typeRoots` cumple dos funciones a la vez. Apunta a `src/dto` para que las interfaces DTO globales se recopilen como archivos de declaración, y mantiene `./node_modules` en la ruta de búsqueda para que `types: ["jjsx"]` se resuelva, ya que `jjsx` no está bajo `@types`.

Configuración de Vite para el cliente

La compilación del cliente se ejecuta en modo middleware porque el servidor Express posee el escuchador HTTP. appType: 'custom' desactiva el propio respaldo de HTML de Vite, ya que Carats renderiza la plantilla HTML por su cuenta.

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  publicDir: path.resolve(import.meta.dirname, 'public'),
  root: path.resolve(import.meta.dirname, 'src/client'),
  base: '/',
  appType: 'custom',
  server: {
    middlewareMode: true
  },
  build: {
    outDir: path.resolve(import.meta.dirname, 'dist/client'),
    emptyOutDir: true,
    manifest: true,
    minify: true,
    rollupOptions: {
      treeshake: true
    }
  }
})

Configuración de Vite para el servidor

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  publicDir: false,
  build: {
    ssr: path.resolve(__dirname, 'src/server/entrypoint.ts'),
    outDir: path.resolve(__dirname, 'dist/server'),
    emptyOutDir: true,
    minify: true,
    rollupOptions: {
      treeshake: true
    }
  }
})

Scripts de package.json

Estos scripts son los puntos de entrada admitidos para desarrollar, compilar y previsualizar una aplicación de Carats.

{
  "scripts": {
    "dev": "bun --inspect=6499 src/app.ts",
    "build": "bun build:server && bun build:client",
    "build:client": "vite build --config vite.config.client.ts",
    "build:server": "vite build --config vite.config.server.ts",
    "build:static": "cross-env NODE_ENV=production carats-ssg",
    "preview": "cross-env NODE_ENV=production bun src/app.ts",
    "test": "vitest --run --coverage"
  }
}

El archivo principal de la aplicación debe estar en `src/app.ts`.

Ejecutar la aplicación

bun run dev inicia la aplicación con el inspector de Bun en el puerto 6499. bun run build empaqueta el servidor y el cliente, y bun run preview sirve la compilación de producción. bun run build:static prerenderiza la aplicación a HTML estático.

Estructura del proyecto

Un proyecto de Carats típico tiene la siguiente estructura:

Siguientes pasos

Lee Conceptos básicos para entender cómo encajan JJSX, las facetas, los culets y las props del servidor, y después mira las páginas Componentes y Renderizado en el servidor.