Başlarken

Bir Carats projesi kurmayı ve sunucu tarafında işlenen bir uygulamayı çalıştırmayı öğrenin.

Gereksinimler

Carats, paket yönetimi ve geliştirme sunucusunu çalıştırmak için Bun kullanır. Bun TSX'i anında derlediği için geliştirme sırasında ayrı bir derleme adımı yoktur. Node.js 20+ da üretim derlemeleri için çalışır, ancak desteklenen yol Bun'dur.

Hızlı başlangıç

Başlamanın en hızlı yolu resmî proje oluşturucusudur. Facet'ler, culet'ler, paylaşılan bir layout, SASS tasarım token'ları ve testler içeren eksiksiz çalışan bir Carats uygulaması yazar; böylece bu belgelerde anlatılan her özellik zaten bağlıdır ve çalışan kod olarak okunabilir.

Yeni bir proje oluştur

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

`bun create carats`, yayımlanmış `create-carats` paketini çözer ve `create-carats` binary'sini çalıştırır; bu da adını verdiğiniz dizine eksiksiz bir Carats projesi yazar. Dizin adı vermezseniz mevcut dizine iskelet oluşturur.

Bağımlılıkları kur ve geliştirme sunucusunu başlat

bun install
bun run dev

Sunucu `http://localhost:5173` adresini dinler. Oluşturulan proje bir panel, bir pazar, bir portföy, bir işlem sayfası, paylaşılan bir layout, bir bulunamadı sayfası ve bir hata sayfası ile gelir; böylece bu belgelerde anlatılan her özellik zaten bağlıdır ve çalışan kod olarak okunabilir.

Manuel kurulum

Boş bir projeyle başlamayı tercih ederseniz aşağıdaki klasör yapısını oluşturup bağımlılıkları kendiniz kurun.

Klasör yapısı

Aşağıdaki klasörleri ve dosyaları oluşturun. Konumlar sabittir, çünkü framework bunları geleneksel yollarla çözer.

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

Bağımlılıkları kur

Carats küçük paketlere ayrılmıştır. Aşağıdaki çalışma zamanı bağımlılıkları tam yığın bir uygulamanın kullandıklarıdır; geliştirme bağımlılıkları ise JJSX derlemesi, SASS ve tip denetimi için gereklidir.

Çalışma zamanı bağımlılıkları

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

Geliştirme bağımlılıkları

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`, Express 5 gerektirir; bu yüzden ana sürüm seçeneğe bırakılmaz.

Yapılandırma

TypeScript yapılandırması

Carats, projenin kökünde bir tsconfig.json dosyası gerektirir. types, jsx, jsxFactory ve jsxFragmentFactory seçenekleri TypeScript'e JJSX'i öğretir; typeRoots ise src/dto içindeki global DTO arayüzlerinin çözülebilmesini sağlar.

{
  "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` iki işi birden yapar. Global DTO arayüzlerinin bildirim dosyası olarak alınması için `src/dto` klasörünü gösterir ve `types: ["jjsx"]` ifadesinin çözülmesi için `./node_modules` dizinini arama yolunda tutar, çünkü `jjsx` `@types` altında bulunmaz.

İstemci Vite yapılandırması

HTTP dinleyicisini Express sunucusu sahiplendiği için istemci derlemesi middleware modunda çalışır. appType: 'custom', HTML'i Carats kendisi işlediğinden Vite'in kendi HTML geri düşmesini devre dışı bırakır.

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
    }
  }
})

Sunucu Vite yapılandırması

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
    }
  }
})

Package.json betikleri

Bu betikler bir Carats uygulamasını geliştirmek, derlemek ve önizlemek için desteklenen giriş noktalarıdır.

{
  "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"
  }
}

Ana uygulama dosyası `src/app.ts` konumunda bulunmalıdır.

Uygulamayı çalıştırma

bun run dev uygulamayı 6499 portunda Bun inspector ile başlatır. bun run build sunucuyu ve istemciyi paketler, bun run preview üretim derlemesini sunar. bun run build:static uygulamayı statik HTML'e önceden işler.

Proje yapısı

Tipik bir Carats projesi şu yapıya sahiptir:

Sonraki adımlar

JJSX'in, facet'lerin, culet'lerin ve sunucu prop'larının bir araya nasıl geldiğini anlamak için Temel Kavramlar sayfasını okuyun, ardından Bileşenler ve Sunucu Tarafı İşleme sayfalarına bakın.