diff --git a/www/src/config.ts b/www/src/config.ts index 49e7be0bc4..6640e9f152 100644 --- a/www/src/config.ts +++ b/www/src/config.ts @@ -26,6 +26,7 @@ export type Frontmatter = { export const KNOWN_LANGUAGES = { en: "đŸ‡ș🇾 English", + de: "đŸ‡©đŸ‡Ș Deutsch", // Add more languages here // sv: "🇾đŸ‡Ș Svenska", } as const; @@ -75,6 +76,34 @@ export const SIDEBAR: Sidebar = { { text: "Docker", link: "en/deployment/docker" }, ], }, + de: { + "Create T3 App": [ + { text: "Einleitung", link: "de/introduction" }, + { text: "Warum CT3A?", link: "de/why" }, + { text: "Installation", link: "de/installation" }, + { text: "Ordnerstruktur", link: "de/folder-structure" }, + { text: "FAQ", link: "de/faq" }, + { text: "T3 Sammlung", link: "de/t3-collection" }, + { text: "Weitere Empfehlungen", link: "de/other-recs" }, + ], + Usage: [ + { text: "Erste Schritte", link: "de/usage/first-steps" }, + { text: "Next.js", link: "de/usage/next-js" }, + { text: "TypeScript", link: "de/usage/typescript" }, + { text: "tRPC", link: "de/usage/trpc" }, + { text: "Prisma", link: "de/usage/prisma" }, + { text: "NextAuth.js", link: "de/usage/next-auth" }, + { + text: "Umgebungsvariablen", + link: "de/usage/env-variables", + }, + { text: "Tailwind CSS", link: "de/usage/tailwind" }, + ], + Deployment: [ + { text: "Vercel", link: "de/deployment/vercel" }, + { text: "Docker", link: "de/deployment/docker" }, + ], + }, // For Translations: // Keep the "outer headers" in English so we can match them. // Translate the "inner headers" to the language you're translating to. @@ -98,4 +127,9 @@ export const SIDEBAR_HEADER_MAP: Record< // Usage: "AnvĂ€ndarguide", // Deployment: "Deployment", // }, + de: { + "Create T3 App": "Create T3 App", + Usage: "Anleitung", + Deployment: "Deployment", + }, }; diff --git a/www/src/pages/de/deployment/docker.md b/www/src/pages/de/deployment/docker.md new file mode 100644 index 0000000000..b610f1fe71 --- /dev/null +++ b/www/src/pages/de/deployment/docker.md @@ -0,0 +1,213 @@ +--- +title: Docker +description: Deployment mit Docker +layout: ../../../layouts/docs.astro +lang: de +--- + +Man kann den Stack mit Docker deployen. Dies ist sowohl als einzelner Container oder als Cluster mit `docker compose` möglich. Ein Beispiel dafĂŒr findet man in dem Repository [`ajcwebdev/ct3a-docker`](https://github.com/ajcwebdev/ct3a-docker), welches auf dieser Dokumentation basiert. + +## Docker Projektkonfiguration + +Next.js benötigt unterschiedliche Vorgehensweisen fĂŒr Variablen, die zur "Build time" gesetzt werden (verfĂŒgbar im Frontend, geprĂ€fixt durch `NEXT_PUBLIC`) und Variablen, die nur serverseitig zur Laufzeit verfĂŒgbar sein sollen. Bitte beachte also die Anordnung der Variablen in der Befehlszeile, der `Dockerfile` und der `docker-compose.yml` Datei. + +- `DATABASE_URL` (wird vom Server verwendet) +- `NEXT_PUBLIC_CLIENTVAR` (wird vom Client verwendet) + +### 1. Next.js Konfiguration + +In der [`next.config.mjs`](https://github.com/t3-oss/create-t3-app/blob/main/cli/template/base/next.config.mjs), muss die output-Option auf `standalone` gesetzt werden, um die GrĂ¶ĂŸe vom Docker-Image zu reduzieren und Gebrauch von ["Output File Tracing"](https://nextjs.org/docs/advanced-features/output-file-tracing) zu machen: + +```diff +export default defineNextConfig({ + reactStrictMode: true, + swcMinify: true, ++ output: "standalone", +}); +``` + +### 2. Erstelle eine dockerignore Datei + +
+ + Klick hier und kopiere den Inhalt in .dockerignore: + +
+ +``` +.env +Dockerfile +.dockerignore +node_modules +npm-debug.log +README.md +.next +.git +``` + +
+ +
+ +### 3. Dockerfile erstellen + +> Da wir die Umgebungsvariablen des Servers nicht in den Container ziehen, wird die [Validierung der Umgebungsvariablen](/de/usage/env-variables) fehlschlagen. Um dies zu verhindern, mĂŒssen wir dem Build-Befehl `SKIP_ENV_VALIDATION=1` hinzufĂŒgen, damit die Umgebungsvariablen-Schemas nicht zur "Build time" validiert werden. + +
+ + Klick hier und kopiere den Inhalt in deinDockerfile: + +
+ +```docker +##### AbhÀngigkeiten + +FROM --platform=linux/amd64 node:16-alpine AS deps +RUN apk add --no-cache libc6-compat openssl +WORKDIR /app + +# Installiere Prisma Client - Entferne diese Zeile wenn du Prisma nicht verwendest + +COPY prisma ./ + +# Installiere die AbhÀngigkeiten basierend auf dem bevorzugten Paketmanager + +COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml\* ./ + +RUN \ + if [ -f yarn.lock ]; then yarn --frozen-lockfile; \ + elif [ -f package-lock.json ]; then npm ci; \ + elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i; \ + else echo "Lockfile not found." && exit 1; \ + fi + +##### BUILDER + +FROM --platform=linux/amd64 node:16-alpine AS builder +ARG DATABASE_URL +ARG NEXT_PUBLIC_CLIENTVAR +WORKDIR /app +COPY --from=deps /app/node_modules ./node_modules +COPY . . + +# ENV NEXT_TELEMETRY_DISABLED 1 + +RUN \ + if [ -f yarn.lock ]; then SKIP_ENV_VALIDATION=1 yarn build; \ + elif [ -f package-lock.json ]; then SKIP_ENV_VALIDATION=1 npm run build; \ + elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && SKIP_ENV_VALIDATION=1 pnpm run build; \ + else echo "Lockfile not found." && exit 1; \ + fi + +##### RUNNER + +FROM --platform=linux/amd64 node:16-alpine AS runner +WORKDIR /app + +ENV NODE_ENV production + +# ENV NEXT_TELEMETRY_DISABLED 1 + +RUN addgroup --system --gid 1001 nodejs +RUN adduser --system --uid 1001 nextjs + +COPY --from=builder /app/next.config.mjs ./ +COPY --from=builder /app/public ./public +COPY --from=builder /app/package.json ./package.json + +COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./ +COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static + +USER nextjs +EXPOSE 3000 +ENV PORT 3000 + +CMD ["node", "server.js"] + +``` + +> **_Notizen_** +> +> - _Emulation von `--platform=linux/amd64` ist gegebenfalls mit Node 18 nicht mehr notwendig._ +> - _Siehe [`node:alpine`](https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine) um zu verstehen warum `libc6-compat` eventuell benötigt wird._ +> - _Next.js erfasst [anonyme Daten zur Nutzung](https://nextjs.org/telemetry). In der obenstehenden `Dockerfile` befinden sich bereits zwei auskommentierte Zeilen mit dem Befehl `ENV NEXT_TELEMETRY_DISABLED 1`. Entferne die Kommentare der ersten Zeile um die Datenerfassung wÀhrend des Builds zu deaktivieren. Die zweite Zeile deaktiviert die Datenerfassung zur Laufzeit._ + +
+
+ +## Erstellung und lokale AusfĂŒhrung des Images + +Erstelle und starte das Image lokal mit folgenden Befehlen: + +```bash +docker build -t ct3a-docker --build-arg NEXT_PUBLIC_CLIENTVAR=clientvar . +docker run -p 3000:3000 -e DATABASE_URL="hier_datenbank_url_einfĂŒgen" ct3a-docker +``` + +Öffne [localhost:3000](http://localhost:3000/) um die laufende Anwendung zu sehen. + +## Docker Compose + +Du kannst auch Docker Compose verwenden, um deine Anwendung zu starten. + +
+ + Verfolge die obenstehenden Schritte 1-4, klicke hier und fĂŒge den Inhalt in docker-compose.yml ein: + +
+ +```yaml +version: "3.9" +services: + app: + platform: "linux/amd64" + build: + context: . + dockerfile: Dockerfile + args: + NEXT_PUBLIC_CLIENTVAR: "clientvar" + working_dir: /app + ports: + - "3000:3000" + image: t3-app + environment: + - DATABASE_URL=hier_datenbank_url_einfĂŒgen +``` + +FĂŒhre den Befehl `docker compose up` aus: + +```bash +docker compose up +``` + +Öffne [localhost:3000](http://localhost:3000/) um die laufende Anwendung zu sehen. + +
+
+ +## Auf Railway deployen + +Du kannst einen PaaS wie [Railway's](https://railway.app) automatisierte [Dockerfile deployments](https://docs.railway.app/deploy/dockerfiles) verwenden um deine Anwendung zu deployen. Wenn du die [Railway CLI installiert hast](https://docs.railway.app/develop/cli#install), kannst du deine Anwendung mit folgenden Befehlen deployen: + +```bash +railway login +railway init +railway link +railway up +railway open +``` + +Gehe zu "Variables" und fĂŒge deine `DATABASE_URL` ein. Anschließend gehe zu "Settings" und wĂ€hle "Generate Domain". Um ein laufendes Beispiel auf Railway zu sehen, besuche [ct3a-docker.up.railway.app](https://ct3a-docker.up.railway.app/). + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| ----------------------------------------------- | -------------------------------------------------------------------- | +| Dockerfile Referenz | https://docs.docker.com/engine/reference/builder/ | +| Compose file version 3 Referenz | https://docs.docker.com/compose/compose-file/compose-file-v3/ | +| Docker CLI Referenz | https://docs.docker.com/engine/reference/commandline/docker/ | +| Docker Compose CLI Referenz | https://docs.docker.com/compose/reference/ | +| Next.js Deployment mit Docker Image | https://nextjs.org/docs/deployment#docker-image | +| Next.js in Docker | https://benmarte.com/blog/nextjs-in-docker/ | +| Next.js mit Docker Beispiel | https://github.com/vercel/next.js/tree/canary/examples/with-docker | +| Erstelle ein Docker Image von einer Next.js app | https://blog.tericcabrel.com/create-docker-image-nextjs-application/ | diff --git a/www/src/pages/de/deployment/vercel.md b/www/src/pages/de/deployment/vercel.md new file mode 100644 index 0000000000..94916e358b --- /dev/null +++ b/www/src/pages/de/deployment/vercel.md @@ -0,0 +1,63 @@ +--- +title: Vercel +description: Deployment mit Vercel +layout: ../../../layouts/docs.astro +lang: de +--- + +Wir empfehlen, deine App auf [Vercel](https://vercel.com/?utm_source=t3-oss&utm_campaign=oss) zu deployen da Vercel es super einfach macht, Next.js Apps zu deployen. + +## Projektkonfiguration + +Vercel wird sehr wahrscheinlich automatisch deinen Build-Befehl konfigurieren und das Verzeichnis veröffentlichen. Du kannst dies aber auch, zusammen mit anderen Konfigurationen, in einer Datei namens [`vercel.json`](https://vercel.com/docs/project-configuration) angeben und folgende Befehle einfĂŒgen: + +```json +{ + "buildCommand": "npm run build", + "outputDirectory": "dist", + "devCommand": "npm run dev", + "installCommand": "npm install" +} +``` + +## Verwendung des Vercel Dashboards + +1. Nachdem du deinen Code in ein GitHub Repository gepusht hast, melde dich bei [Vercel](https://vercel.com/?utm_source=t3-oss&utm_campaign=oss) mit GitHub an und klicke auf **Add New Project**. + +![New project on Vercel](/images/vercel-new-project.webp) + +2. Importiere das GitHub Repository mit deinem Projekt, welches du deployen möchtest. + +![Import repository](/images/vercel-import-project.webp) + +3. FĂŒge deine Umgebungsvariablen hinzu. + +![Add environment variables](/images/vercel-env-vars.webp) + +4. Klicke auf **Deploy**. Wenn du nun einen Push in dein Repository machst, wird Vercel automatisch deine App neu deployen! + +## Verwendung der Vercel CLI + +Um deine App von der Kommandozeile zu deployen, musst du zuerst die Vercel CLI global [installieren](https://vercel.com/docs/cli#installing-vercel-cli). + +```bash +npm i -g vercel +``` + +FĂŒhre den [`vercel`](https://vercel.com/docs/cli/deploying-from-cli) Befehl aus, um dein Projekt zu deployen. + +```bash +vercel +``` + +FĂŒge `--env DATABASE_URL=YOUR_DATABASE_URL_HERE` fĂŒr Umgebungsvariablen wie die Datenbankverbindung hinzu. Verwende `--yes`, wenn du die Deployment-Fragen ĂŒberspringen möchtest und die Standardantwort fĂŒr jede geben möchtest. + +```bash +vercel --env DATABASE_URL=YOUR_DATABASE_URL_HERE --yes +``` + +Nach dem ersten Deployment wird dieser Befehl auf einen Preview-Branch deployen. Du musst `--prod` hinzufĂŒgen, um Änderungen direkt auf die Produktivsystem zu pushen. + +```bash +vercel --prod +``` diff --git a/www/src/pages/de/faq.md b/www/src/pages/de/faq.md new file mode 100644 index 0000000000..d9c6d82c71 --- /dev/null +++ b/www/src/pages/de/faq.md @@ -0,0 +1,59 @@ +--- +title: FAQ +description: HĂ€ufig gestellte Fragen zu Create T3 App +layout: ../../layouts/docs.astro +lang: de +--- + +Hier sind einige hĂ€ufig gestellte Fragen zu `create-t3-app`. + +## Was kommt als nĂ€chstes? Wie erstelle ich eine App mit diesem Tool? + +Wir versuchen, dieses Projekt so einfach wie möglich zu halten damit du einfach mit dem GrundgerĂŒst starten kannst, welches wir fĂŒr dich erstellt haben. Weitere Dinge kannst du spĂ€ter hinzufĂŒgen, sobald diese notwendig werden. + +Wenn du mit den verschiedenen Technologien, die in diesem Projekt verwendet werden, nicht vertraut bist, dann schau dir bitte die entsprechenden Dokumentationen an. Wenn du weitere Fragen hast, dann trete unserem [Discord](https://t3.gg/discord) bei und frag nach Hilfe. + +- [Next.js](https://nextjs.org/) +- [NextAuth.js](https://next-auth.js.org) +- [Prisma](https://prisma.io) +- [Tailwind CSS](https://tailwindcss.com) +- [tRPC](https://trpc.io) + +## Welches Lernmaterial ist aktuell verfĂŒgbar? + +Auch wenn die unten aufgefĂŒhrten Ressourcen zu den besten gehören, die fĂŒr die T3-Stack existieren, empfiehlt die Community (und [Theo](https://youtu.be/rzwaaWH0ksk?t=1436)) dir, dass du einfach mit dem Stack anfĂ€ngst und etwas damit erstellst, wĂ€hrend du lernst. + +Wenn du `create-t3-app` in Betracht ziehst, dann hast du wahrscheinlich schon einige Teile des Stacks verwendet. Warum springst du also nicht einfach ins kalte Wasser und lernst die anderen Teile, wĂ€hrend du etwas erstellst? + +Wir wissen, dass dieser Weg nicht fĂŒr jeden funktioniert. Wenn du dir also sicher bist, dass du die Empfehlung ausprobiert hast und trotzdem noch einige Ressourcen haben möchtest, oder du einfach nicht selbstbewusst genug bist, um es alleine zu tun und/oder von dem Stack ĂŒberwĂ€ltigt bist, dann schau dir diese tollen Tutorials zu `create-t3-app` an: + +### Artikel + +- [Build a full stack app with create-t3-app](https://www.nexxel.dev/blog/ct3a-guestbook) +- [A first look at create-t3-app](https://dev.to/ajcwebdev/a-first-look-at-create-t3-app-1i8f) +- [Migrating your T3 App into a Turborepo](https://www.jumr.dev/blog/t3-turbo) + +### Videos + +- [Build a Blog With the T3 Stack - tRPC, TypeScript, Next.js, Prisma & Zod](https://www.youtube.com/watch?v=syEWlxVFUrY) +- [Build a Live Chat Application with the T3 Stack - TypeScript, Tailwind, tRPC](https://www.youtube.com/watch?v=dXRRY37MPuk) +- [The T3 Stack - How We Built It](https://www.youtube.com/watch?v=H-FXwnEjSsI) +- [An overview of the create T3 App (Next, Typescript, Tailwind, tRPC, Next-Auth)](https://www.youtube.com/watch?v=VJH8dsPtbeU) + +## Warum befinden sich `.js` Dateien im Projekt? + +Wie in [T3-Axiom #3](/de/introduction#typesafety-isnt-optional) beschrieben, nehmen wir Typsicherheit sehr ernst. Leider unterstĂŒtzen nicht alle Frameworks und Plugins TypeScript, was bedeutet, dass einige Konfigurationsdateien `.js`-Dateien sein mĂŒssen. + +Wir versuchen hervorzuheben, dass diese Dateien aus einem bestimmten Grund in JavaScript geschrieben sind, indem wir den Typ (`cjs` oder `mjs`) jeder Datei explizit deklarieren (abhĂ€ngig davon, was von der zugehörigen Bibliothek unterstĂŒtzt wird). Außerdem werden alle `js`-Dateien in diesem Projekt weiterhin mit einem `@ts-check`-Kommentar am Anfang auf korrekte Typen geprĂŒft. + +## Ich habe Schwierigkeiten, i18n zu meiner App hinzuzufĂŒgen. Gibt es eine Referenz, die ich verwenden kann? + +Wir haben uns dazu entschieden, i18n nicht standardmĂ€ĂŸig in `create-t3-app` einzubinden, da es ein sehr kontroverses Thema ist und es viele Möglichkeiten gibt, dies zu implementieren. + +Wenn du jedoch Schwierigkeiten hast, dies zu implementieren und eine Referenzprojekt sehen möchtest, haben wir ein [Referenzrepo](https://github.com/juliusmarminge/t3-i18n), das zeigt, wie du i18n zu einer T3-App mit [next-i18next](https://github.com/i18next/next-i18next) hinzufĂŒgen kannst. + +## Warum verwenden wir `/pages` und nicht `/app` von Next.js 13? + +Wie in [T3-Axiom #2](/de/introduction#bleed-responsibly) beschrieben lieben wir neue Technologien, jedoch legen wir großen Wert auf StabilitĂ€t. Deinen gesamten Router umzuziehen ist schwierig und es ist keine gute Idee an einer so elementaren Stelle diese Risiken einzugehen (siehe [bleed responsibly](<(https://youtu.be/mnwUbtieOuI?t=1662)>)). Auch wenn `/app` ein [Vorgeschmack auf die Zukunft](https://youtu.be/rnsC-12PVlM?t=818) ist, ist es noch nicht fĂŒr bereit im Produktivbetrieb eingesetzt zu werden. Die API befindet sich noch in der Beta und wird wahrscheinlich noch Breaking Changes haben. + +Schau dir die [Beta Next.js Dokumentation](https://beta.nextjs.org/docs/app-directory-roadmap#supported-and-planned-features) an um eine Liste der unterstĂŒtzten, geplanten und in Arbeit befindlichen Funktionen im `/app`-Verzeichnis zu sehen. diff --git a/www/src/pages/de/folder-structure.md b/www/src/pages/de/folder-structure.md new file mode 100644 index 0000000000..9ac95d28cb --- /dev/null +++ b/www/src/pages/de/folder-structure.md @@ -0,0 +1,228 @@ +--- +title: Ordnerstruktur +description: Ordnerstruktur einer neu erstellten T3 App +layout: ../../layouts/docs.astro +lang: de +--- + +Nachfolgend ist die Ordnerstruktur einer neu erstellten T3 App zu sehen, bei der alle Optionen ausgewĂ€hlt wurden. + +Die Beschreibung jedes Ordners gibt an, welchen Zweck dieser erfĂŒllt und ob dieser nur bei ausgewĂ€hlten Bibliotheken enthalten ist. + +``` +. +├─ prisma +│ └─ schema.prisma +├─ public +│ └─ favicon.ico +├─ src +│ ├─ env +│ │ ├─ client.mjs +│ │ ├─ schema.mjs +│ │ └─ server.mjs +│ ├─ pages +│ │ ├─ api +│ │ │ ├─ auth +│ │ │ │ └─ [...nextauth].ts +│ │ │ ├─ trpc +│ │ │ │ └─ [trpc].ts +│ │ │ ├─ examples.ts +│ │ │ └─ restricted.ts +│ │ ├─ _app.tsx +│ │ └─ index.tsx +│ ├─ styles +│ │ └─ globals.css +│ ├─ types +│ │ └─ next-auth.d.ts +│ ├─ utils +│ │ └─ trpc.ts +│ ├─ server +│ │ ├─ common +│ │ │ └─ get-server-auth-session.ts +│ │ ├─ db +│ │ │ └─ client.ts +│ │ └─ trpc +│ │ ├─ router +│ │ │ ├─ _app.ts +│ │ │ ├─ auth.ts +│ │ │ └─ example.ts +│ │ ├─ context.ts +│ │ └─ trpc.ts +├─ .env +├─ .env.example +├─ .eslintrc.json +├─ next-env.d.ts +├─ next.config.mjs +├─ postcss.config.cjs +├─ prettier.config.cjs +├─ tailwind.config.cjs +└─ tsconfig.json +``` + +### `prisma` + +Der `prisma` Ordner enthĂ€lt die `schema.prisma` Datei, die zur Konfiguration der Datenbankverbindung und des Datenbankschemas verwendet wird. Es ist auch der Ort, um Migrationsdateien und / oder Seed-Skripte zu speichern, wenn sie verwendet werden. Weitere Informationen findest du unter [Verwendung von Prisma](/de/usage/prisma). + +(mit Prisma) + +### `public` + +Der `public` Ordner enthĂ€lt statische Assets, die vom Webserver bereitgestellt werden. Die `favicon.ico` Datei ist ein Beispiel fĂŒr ein statisches Asset. + +### `src/env` + +Wird benutzt fĂŒr die Validierung von Umgebungsvariablen und Typdefinitionen - siehe [Umgebungsvariablen](/de/usage/env-variables). + +### `src/pages` + +Der `pages` Ordner enthĂ€lt alle Seiten der Next.js Anwendung. Die `index.tsx` Datei im Root-Verzeichnis von `/pages` ist die Startseite der Anwendung. Die `_app.tsx` Datei wird verwendet, um die Anwendung mit Providern zu umschließen. Weitere Informationen findest du in der [Next.js Dokumentation](https://nextjs.org/docs/basic-features/pages). + +#### `src/pages/api` + +Der `api` Ordner enthĂ€lt alle API-Routen der Next.js Anwendung. Die `examples.ts` Datei (mit Prisma) enthĂ€lt ein Beispiel fĂŒr eine Route, die das [Next.js API route](https://nextjs.org/docs/api-routes/introduction)-Feature mit Prisma verwendet. Die `restricted.ts` Datei (mit Next-Auth) enthĂ€lt ein Beispiel fĂŒr eine Route, die das [Next.js API route](https://nextjs.org/docs/api-routes/introduction)-Feature verwendet und durch [NextAuth.js](https://next-auth.js.org/) geschĂŒtzt ist. + +(Mit NextAuth.js, tRPC oder tRPC + Prisma) + +#### `src/pages/api/auth/[...nextauth].ts` + +Die `[...nextauth].ts` Datei ist die NextAuth.js Authentifizierung Slug Route. Sie wird verwendet, um Authentifizierungsanfragen zu verarbeiten. Weitere Informationen zu NextAuth.js findest du unter [Verwendung von NextAuth.js](/de/usage/next-auth) und [Next.js Dynamic Routes Docs](https://nextjs.org/docs/routing/dynamic-routes) fĂŒr Informationen zu Catch-All/Slug Routen. + +(mit NextAuth.js) + +#### `src/pages/api/trpc/[trpc].ts` + +Die `[trpc].ts` Datei ist der tRPC API-Einstiegspunkt. Sie wird verwendet, um tRPC-Anfragen zu verarbeiten. Weitere Informationen zu dieser Datei findest du unter [tRPC Verwendung](/de/usage/trpc#-pagesapitrpctrpcts) und [Next.js Dynamic Routes Docs](https://nextjs.org/docs/routing/dynamic-routes) fĂŒr Informationen zu Catch-All/Slug Routen. + +(mit tRPC) + +### `src/server` + +Der `server` Ordner wird verwendet um den serverseitigen Code eindeutig von dem clientseitigen Code zu trennen. + +(mit tRPC und/oder Prisma) + +### `src/server/common` + +Der `common` Ordner enthĂ€lt hĂ€ufig wiederverwendeten serverseitigen Code. + +(mit NextAuth.js + tRPC) + +#### `src/server/common/get-server-auth-session.ts` + +Die `get-server-auth-session.ts` Datei wird verwendet, um die NextAuth.js Sitzung serverseitig zu erhalten. Weitere Informationen findest du unter [Verwendung von NextAuth.js](/de/usage/next-auth#verwendung-mit-trpc). + +(mit NextAuth.js + tRPC) + +#### `src/server/db/client.ts` + +Die `client.ts` Datei wird verwendet, um den Prisma-Client auf globaler Ebene zu initialisieren. Weitere Informationen findest du unter [Verwendung von Prisma](/de/usage/prisma#prisma-client). + +(mit Prisma) + +### `src/server/trpc` + +Der `trpc` Ordner enthĂ€lt den serverseitigen tRPC-Code. + +(with tRPC) + +#### `src/server/trpc/context.ts` + +Die `content.ts` Datei wird verwendet, um den Kontext zu erstellen, der in tRPC-Anfragen verwendet wird. Weitere Informationen findest du unter [Verwendung von tRPC](/de/usage/trpc#-servertrpccontextts). + +(mit tRPC) + +#### `src/server/trpc/trpc.ts` + +Die `trpc.ts` Datei wird verwendet, um die Helferfunktionen fĂŒr die Prozeduren zu exportieren. Weitere Informationen findest du unter [Verwendung von tRPC](/de/usage/trpc#-servertrpctrpcts). + +(mit tRPC) + +### `src/server/trpc/router` + +Der `router` Ordner enthĂ€lt die tRPC-Routen. + +(mit tRPC) + +#### `src/server/trpc/router/_app.ts` + +Die `_app.ts` Datei wird verwendet, um tRPC-Routen zusammenzufĂŒhren und diese als einzelnen Router sowie die Typdefinitionen zu exportieren. Weitere Informationen findest du unter [Verwendung von tRPC](/de/usage/trpc#-servertrpcrouterts). + +(mit tRPC) + +#### `src/server/trpc/router/auth.ts` + +Die `auth.tsÂŽ Datei ist ein Beispiel fĂŒr eine tRPC-Route, die die `protectedProcedure`-Hilfsfunktion verwendet, um zu demonstrieren, wie eine tRPC-Routen mit NextAuth.js geschĂŒtzt werden kann. + +(mit NextAuth.js + tRPC) + +#### `src/server/trpc/router/example.ts` + +Die `example.ts` Datei ist ein Beispiel fĂŒr einen tRPC-Router, der die `publicProcedure`-Hilfsfunktion verwendet, um zu demonstrieren, wie eine tRPC-Routen ohne Authentifizierung erstellt werden kann. + +(mit tRPC) + +### `src/styles` + +Der `styles` Ordner enthĂ€lt die globalen Styles der Anwendung. + +(mit Tailwind CSS) + +### `src/types` + +Der `types` Ordner wird verwendet, um wiederverwendete Typen oder Typdeklarationen zu speichern. + +(mit NextAuth.js) + +#### `src/types/next-auth.d.ts` + +Die `next-auth.d.ts` Datei wird verwendet, um den Standardtyp der NextAuth-Sitzung um die Benutzer-ID zu erweitern. Weitere Informationen findest du unter [Verwendung von NextAuth.js](/de/usage/next-auth#inclusion-of-userid-on-the-session). + +(mit NextAuth.js) + +### `src/utils` + +Der `utils` Ordner wird verwendet, um hĂ€ufig wiederverwendete Hilfsfunktionen zu speichern. + +(mit tRPC) + +#### `src/utils/trpc.ts` + +Die `trpc.ts` Datei ist der clientseitige Einstiegspunkt fĂŒr tRPC. Weitere Informationen findest du unter [Verwendung von tRPC](/de/usage/trpc#-utilstrpcts). + +(mit tRPC) + +### `.env` + +Die `.env` Datei wird verwendet, um Umgebungsvariablen bereitzustellen. Weitere Informationen findest du unter [Umgebungsvariablen](/de/usage/env-variables). Diese Datei sollte **nicht** committed werden. + +### `.env.example` + +Die `.env.example` Datei zeigt Beispiele fĂŒr Umgebungsvariablen basierend auf den ausgewĂ€hlten Bibliotheken. Diese Datei sollte **nicht** committed werden. + +### `.eslintrc.json` + +Die `.eslintrc.json` Datei wird verwendet, um ESLint zu konfigurieren. Weitere Informationen findest du in der [ESLint Dokumentation](https://eslint.org/docs/latest/user-guide/configuring/configuration-files). + +### `next-env.d.ts` + +Die `next-env.d.ts` Datei stellt sicher, dass die Next.js Typen vom TypeScript-Compiler erkannt werden. **Du solltest sie nicht entfernen oder bearbeiten, da sie jederzeit geĂ€ndert werden kann.** Weitere Informationen findest du in der [Next.js Dokumentation](https://nextjs.org/docs/basic-features/typescript#existing-projects). + +### `next.config.mjs` + +Die `next.config.mjs` Datei wird verwendet, um Next.js zu konfigurieren. Weitere Informationen findest du in der [Next.js Dokumentation](https://nextjs.org/docs/api-reference/next.config.js/introduction). Hinweis: Die .mjs Dateiendung wird verwendet, um ESM-Importe zu ermöglichen. + +### `postcss.config.cjs` + +Die `postcss.config.cjs` Datei wird fĂŒr die Verwendung von Tailwind PostCSS verwendet. Weitere Informationen findest du in der [Taiwind PostCSS Dokumentation](https://tailwindcss.com/docs/installation/using-postcss). + +(mit Tailwind CSS) + +### `prettier.config.cjs` + +Die `prettier.config.cjs` Datei wird verwendet, um Prettier zu konfigurieren und das prettier-plugin-tailwindcss fĂŒr die Formatierung von Tailwind CSS-Klassen zu verwenden. Weitere Informationen findest du im [Tailwind CSS Blogbeitrag](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier). + +(mit Tailwind CSS) + +### `tsconfig.json` + +Die `tsconfig.json` Datei wird verwendet, um TypeScript zu konfigurieren. Einige nicht-Standardwerte, wie `strict mode` wurden aktiviert, um die beste Verwendung von TypeScript fĂŒr `create-t3-app` und die verwendeten Bibliotheken zu gewĂ€hrleisten. Weitere Informationen findest du in der [TypeScript Dokumentation](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) und [Verwendung von TypeScript](/de/usage/typescript). diff --git a/www/src/pages/de/installation.md b/www/src/pages/de/installation.md new file mode 100644 index 0000000000..627c13d26b --- /dev/null +++ b/www/src/pages/de/installation.md @@ -0,0 +1,61 @@ +--- +title: Installation +description: Anleitung zur Installation von Create T3 App +layout: ../../layouts/docs.astro +lang: de +--- + +Um eine App mit `create-t3-app` zu erstellen, fĂŒhre eines der folgenden drei Befehle aus und beantworte die Fragen ĂŒber dein Terminal: + +### npm + +```bash +npm create t3-app@latest +``` + +### yarn + +```bash +yarn create t3-app +``` + +### pnpm + +```bash +pnpm create t3-app@latest +``` + +Nachdem deine App erstellt wurde, schau dir die [ersten Schritte](/de/usage/first-steps) an, um mit der Entwicklung deiner neuen App zu beginnen. + +## Erweiterte Nutzung + +| Option/Flag | Beschreibung | +| ----------------- | -------------------------------------------------------------------------------------------- | +| `[dir]` | FĂŒge ein Ordner Argument hinzu mit dem Namen fĂŒr das Projekt | +| `--noGit` | Explizit der CLI sagen, dass keine neues git repo fĂŒr das Projekt initialisiert werden soll | +| `-y`, `--default` | Die CLI wird ĂŒbersprungen und eine neue t3-app mit allen ausgewĂ€hlten Optionen wird erstellt | +| `--noInstall` | Erstellt das Projekt ohne die AbhĂ€ngigkeiten zu installieren | + +## Experimentelle Nutzung + +Wir haben einige experimentelle Flags, die es dir ermöglichen, eine App ohne jegliche Prompts zu erstellen. Wenn du davon Gebrauch machen möchtest, kannst du diese Flags verwenden. Bitte beachte, dass diese Flags experimentell sind und sich in Zukunft ohne semver Versionierung Ă€ndern können. + +| Flag | Beschreibung | +| ------------ | -------------------------------------------------- | +| `--CI` | Teilt der CLI mit das wir uns im CI Modus befinden | +| `--trpc` | FĂŒgt tRPC zum Projekt hinzu | +| `--prisma` | FĂŒgt Prisma zum Projekt hinzu | +| `--nextAuth` | FĂŒgt NextAuth.js zum Projekt hinzu | +| `--tailwind` | FĂŒgt Tailwind CSS zum Projekt hinzu | + +**Hinweis: Wenn du die `CI` Flag nicht angibst, haben die restlichen Flags keine Auswirkung.** + +Du musst nicht explizit die Pakete ausschließen, die du nicht möchtest. Wenn du aber explizit sein möchtest, kannst du `false` ĂŒbergeben, z.B. `--nextAuth false`. + +### Beispiel + +Die folgende Eingabe wĂŒrde eine t3-app mit tRPC und Tailwind CSS erstellen. + +```bash +pnpm dlx create-t3-app@latest --CI --trpc --tailwind +``` diff --git a/www/src/pages/de/introduction.md b/www/src/pages/de/introduction.md new file mode 100644 index 0000000000..8b2cbc7a52 --- /dev/null +++ b/www/src/pages/de/introduction.md @@ -0,0 +1,42 @@ +--- +title: Einleitung +description: EinfĂŒhrung in den T3 Stack +layout: ../../layouts/docs.astro +lang: de +--- + +
+ +
+ +## Der T3 Stack + +Der _"T3 Stack"_ ist ein Webentwicklungsstack von [Theo](https://twitter.com/t3dotgg), der sich auf Einfachheit, ModularitĂ€t und vollstĂ€ndige Typensicherheit konzentriert. + +Im Kern besteht er aus [**Next.js**](https://nextjs.org/) und [**TypeScript**](https://typescriptlang.org/). [**Tailwind CSS**](https://tailwindcss.com/) wird auch fast immer verwendet. Sobald Backend-FunktionalitĂ€ten benötigt werden, sind [**tRPC**](https://trpc.io/), [**Prisma**](https://prisma.io/) und [**NextAuth.js**](https://next-auth.js.org/) ebenfalls gute ErgĂ€nzungen. + +Du hast vielleicht bemerkt, dass der T3-Stack viele Bestandteile hat. Das ist so gewollt. Tausche die Teile aus, wenn du sie brauchst - der Stack ist im Kern modular :) + +## Also... was ist create-t3-app? Ein Template? + +Irgendwie? `create-t3-app` ist eine CLI, die von erfahrenen T3-Stack-Entwicklern entwickelt wurde, um die Einrichtung einer modularen T3-Stack-App zu vereinfachen. Das bedeutet, dass jeder Bestandteil optional ist und das "Template" auf der Grundlage deiner spezifischen Anforderungen erstellt wird. + +Nach unzĂ€hligen Projekten und vielen Jahren auf diesem Gebiet haben wir viele Meinungen und Erkenntnisse. Wir haben unser Bestes getan, um sie in dieser CLI zu verwirklichen. + +Das hier ist **KEINE** allumfassende Vorlage. Wir **erwarten**, dass du deine eigenen Bibliotheken einbringst, die die Anforderungen **DEINER** Anwendung erfĂŒllen. Wir wollen zwar keine Lösungen fĂŒr spezifischere Probleme wie Zustandsverwaltung und Deployment vorschreiben, aber wir [haben hier einige Empfehlungen aufgelistet](/de/other-recs). + +## T3 GrundsĂ€tze + +Das Projekt wurde nach _unseren Vorstellungen_ gestaltet. Wir teilen eine Reihe an Überzeugungen fĂŒr das Erstellen von Web-Applikationen und nutzen diese als Basis fĂŒr unsere Entscheidungen. + +### Probleme lösen + +Es ist leicht, in die Falle zu tappen, "alles hinzuzufĂŒgen" - das wollen wir ausdrĂŒcklich nicht tun. Alles, was zu `create-t3-app` hinzugefĂŒgt wird, sollte ein spezifisches Problem lösen, das innerhalb der enthaltenen Kerntechnologien existiert. Das bedeutet, dass wir keine Technologien wie Zustandsbibliotheken (`zustand`, `redux`) hinzufĂŒgen werden. Wir werden jedoch Dinge wie NextAuth.js, Prisma und tRPC integrieren. + +### Modern und verantwortungsbewusst + +Wir lieben moderne Technologien. Die Arbeitsgeschwindigkeit und der Spaß aus der Arbeit mit ihnen, ist wirklich cool. Wir denken aber, dass es wichtig ist, verantwortungsvoll zu sein und riskantere Technologien in den weniger riskanten Teilen des Stacks zu verwenden. Das bedeutet, dass wir nicht ⛔ auf riskante neue Datenbanktechnologien setzen (SQL ist toll!). Aber wir setzen gerne ✅ auf tRPC, da es sich nur auf Funktionen bezieht, die trivial zu verlagern sind. + +### Typsicherheit ist nicht optional + +Das erklĂ€rte Ziel von `create-t3-app` ist es, den schnellsten Weg zu einer neuen, **typsicheren** Full-Stack Webanwendung zu bieten. Wir nehmen die Typsicherheit ernst, da sie unsere ProduktivitĂ€t verbessert und uns hilft, weniger Fehler auszuliefern. Jede Entscheidung, die die Typsicherheit von `create-t3-app` gefĂ€hrdet, sollte in einem anderen Projekt getroffen werden. diff --git a/www/src/pages/de/other-recs.md b/www/src/pages/de/other-recs.md new file mode 100644 index 0000000000..46c5d0f8c5 --- /dev/null +++ b/www/src/pages/de/other-recs.md @@ -0,0 +1,163 @@ +--- +title: Weitere Empfehlungen +description: Bibliotheken und Dienste, die wir fĂŒr viele Projekte empfehlen +layout: ../../layouts/docs.astro +lang: de +--- + +Wir sind uns bewusst darĂŒber, dass die Bibliotheken, die in `create-t3-app` enthalten sind, nicht jedes Problem lösen. +WĂ€hrend wir dich dazu ermutigen möchten dein Projekt mit den Dingen zu beginnen, die wir zur VerfĂŒgung stellen, wird es sicherlich zu ein Zeitpunkt kommen, an dem du andere Pakete einbinden musst. Nur du kannst wissen, was dein Projekt braucht, aber hier sind einige Dinge, die wir gerne und hĂ€ufig empfehlen. + +Diese Empfehlungen stammen von einzelnen create-t3-app Mitwirkenden und sollte nicht als "offizielle" Bekanntmachung +durch das create-t3-app Team oder T3-OSS gesehen werden. _**Bitte fĂŒhre deine eigene Recherche durch, insbesondere bevor du dich fĂŒr kostenpflichtige Dienste entscheidest**_. + +## State Management + +_**Hinweis**_: State Management Bibliotheken können großartig sein sind aber oft nicht notwendig. Die tRPC's React Query Hooks sollten in der Lage sein deinen Server State zu verwalten. FĂŒr Client State solltest du mit `useState` von React beginnen und auf einer dieser Optionen zurĂŒckgreifen, wenn du mehr brauchst. + +### Zustand + +**Um nie wieder Redux verwenden zu mĂŒssen** + +Das "moderne, einfache Redux" von dem du nicht wusstest, dass du es brauchst. [Poimandres](https://github.com/pmndrs) kann immer vertraut werden. Mit dieser kleinen Bibliothek kannst du alles von Videokonferenz-Apps bis hin zu Spielen und Servern erstellen. + +- [Zustand Homepage](https://zustand-demo.pmnd.rs/) +- [Zustand GitHub](https://github.com/pmndrs/zustand) + +### Jotai + +**Um nie wieder Context verwenden zu mĂŒssen** + +Jotai ist schwer zu schlagen, wenn ein atomarer Ansatz bevorzugt wird. Ebenfalls von [Poimandres](https://github.com/pmndrs). Jotai ermöglicht es dir, Singletons zu definieren, die sich wie globale useState anfĂŒhlen. Eine großartige Option fĂŒr States, die noch nicht eine State Machine benötigen. + +- [Jotai Homepage](https://jotai.org/) +- [Jotai GitHub](https://github.com/pmndrs/jotai) + +## Komponentenbibliotheken + +Die meisten Apps benötigen die gleichen Ă€hnlichen Komponenten - Toggle Buttons, Dropdown MenĂŒs, Modals usw. Diese Bibliotheken bieten großartige, barrierefreie Komponenten, die du verwenden und an deine BedĂŒrfnisse anpassen kannst. + +### Ungestaltete Komponentenbibliotheken + +Solche Bibliotheken sind auch bekannt als Headless Libraries. Sie bieten großartige, ungestylte und barrierefreie Komponenten, die du nach deinem Geschmack anpassen kannst. Hier sind ein paar Empfehlungen. + +- [Radix UI](https://www.radix-ui.com/) bietet dir ein mĂ€chtiges Set an praktischen und barrierefreien primitiven Komponenten, die du mit Vanilla CSS, Tailwind CSS und mehr stylen kannst. + +- [Headless UI](https://headlessui.com/) wurde von dem Tailwind CSS Team erstellt und bietet ebenfalls ungestylte, barrierefreie Komponenten, die problemlos mit Tailwind CSS verwenden kannst. + +- [React Aria](https://react-spectrum.adobe.com/react-aria/) eine große Sammlung an React Hooks um barrierefrei Komponente erstellen zu können. Deren Date Picker ist top. + +### Gestaltete Komponentenbibliotheken + +**Wenn du einfach nur eine App haben willst, die OK aussieht** + +Manchmal möchtest du ein Projekt erstellen, bei dem die UI direkt in Ordnung aussieht. Das könnte zum Beispiel der Fall bei Admin Dashboards oder Ă€hnlichen Projekten sein. FĂŒr solche Projekte sind alle diese Komponentenbibliotheken eine gute Wahl. + +- [Chakra UI](https://chakra-ui.com) +- [Mantine](https://mantine.dev) + +### Class Variance Authority + +**Um UI Bibliotheken zu erstellen** + +Ermöglicht es dir deklarativ eine UI Bibliothek mit verschiedenen Farben, GrĂ¶ĂŸen usw. Varianten zu erstellen. Wenn dein Projekt eine GrĂ¶ĂŸe erreicht hat, bei der du ein standardisiertes Set an UI Komponenten mit mehreren Varianten mit Tailwind CSS haben möchtest, ist CVA ein großartiges Tool. + +- [Class Variance Authority GitHub](https://github.com/joe-bell/cva) + +## Animationen + +Hier sind unsere Empfehlungen, wenn du du Animationen in deiner App benötigst. + +### AutoAnimate + +**FĂŒr Animationen mit nur einer Zeile Code** + +Die meisten Animations Bibliotheken versuchen alle möglichen AnwendungsfĂ€lle zu erfĂŒllen und werden dadurch unhandlich. AutoAnimate ist ein Tool ohne Konfiguration, das dir eine signifikante UX-Verbesserung ohne zusĂ€tzlichen Entwickleraufwand bringt. + +- [AutoAnimate Homepage](https://auto-animate.formkit.com/) +- [AutoAnimate GitHub](https://github.com/formkit/auto-animate) +- [AutoAnimate Component Snippet](https://gist.github.com/hwkr/3fdea5d7f609b98c162e5325637cf3cb) + +### Framer Motion + +**FĂŒr komplexe Animationen mit deklarativem Code** + +Framer Motion bietet eine einfache, deklarative Syntax und ermöglicht es dir mit wenig Zeilen an Code komplexe Animationen bis hin zu Gesten zu erstellen. + +- [Framer Motion Homepage](https://framer.com/motion) +- [Framer Motion Documentation](https://www.framer.com/docs/) + +## Deployments, Infrastruktur, Datenbanken und CI + +### Vercel + +**Um deine App zu hosten** + +Vercel hat das Hosting von Web Apps zu einem Kinderspiel gemacht. Wir haben unsere App auf Hunderttausende von Nutzern hochskaliert und es gab nie Probleme. Betrieben durch AWS und mit einer viel besseren BenutzeroberflĂ€che. + +- [Vercel Homepage](https://vercel.com/) +- [Create T3 App Vercel deployment guide](/en/deployment/vercel) + +### PlanetScale + +**FĂŒr Datenbanken ohne sich Sorgen machen zu mĂŒssen** + +PlanetScale ist die beste "serverless Datenbank Plattform" die wir bisher verwendet haben. Wahnsinnige Skalierbarkeit, großartige Entwicklerzufriedenheit und fantastische Preise. Wenn du SQL verwendest (und hoffentlich Prisma) ist es schwer dies zu schlagen. + +- [PlanetScale Homepage](https://planetscale.com/) + +### Railway + +**Um deine Infrastruktur zu hosten** + +"Das moderne Heroku". Die einfachste Möglichkeit einen echten Server hochzufahren. Wenn Vercel und PlanetScale nicht ausreichen, ist Railway wahrscheinlich die beste Wahl. Einfach auf ein GitHub Repo zeigen und loslegen. + +- [Railway Homepage](https://railway.app/) + +### Upstash + +**FĂŒr serverless Redis** + +Wir lieben Prisma und PlanetScale, aber manche Projekt benötigten manchmal eine performantere Lösung. Upstash ermöglicht es die in-memory Performance von Redis in deinem serverless Projekt zu nutzen, ohne sich um die Infrastruktur und Skalierung kĂŒmmern zu mĂŒssen. + +- [Upstash Homepage](https://upstash.com/) + +### Pusher + +**FĂŒr serverless WebSockets** + +Wenn WebSockets der Hauptfokus deines Projekts sind, solltest du vielleicht eine traditionellere Backend Lösung wie [Fastify](https://www.fastify.io/) (welche [auch mit tRPC funktioniert!](https://trpc.io/docs/v10/fastify)) in Betracht ziehen. FĂŒr das schnelle HinzufĂŒgen von WebSockets zu einer T3 App ist Pusher eine ausgezeichnete Wahl. + +- [Pusher Homepage](https://pusher.com/) + +### Soketi + +Soketi ist eine selbsthostbare, einfache und schnelle Alternative zu Pusher. Es ist vollstĂ€ndig kompatibel mit der Pusher SDK, welches du verwenden kannst um dich mit dem Server zu verbinden. Soketi serverless befindet sich aktuell noch in der Beta. + +- [Soketi Homepage](https://soketi.app) +- [Soketi GitHub](https://github.com/soketi/soketi) + +## Analytics + +Benutzerdaten sind sehr wertvoll, wenn du eine App entwickelst. Hier sind einige Analytics Provider die wir empfehlen. + +### Plausible + +Du benötigst Analytics? Plausible ist einer der schnellsten Wege. Super minimal und es gibt sogar ein [einfaches Plugin fĂŒr Next.js](https://plausible.io/docs/proxy/guides/nextjs). + +- [Plausible Homepage](https://plausible.io/) + +### Umami + +Umami ist eine selbsthostbare, einfache, schnelle und datenschutzfreundliche Alternative zu Google Analytics. Du kannst es sehr einfach auf Vercel, Railway, etc. mit PlanetScale als Datenbank hosten. + +- [Umami Homepage](https://umami.is/) +- [Umami GitHub](https://github.com/umami-software/umami) + +## Other + +### Next Bundle Analyzer + +Manchmal ist es schwierig herauszufinden welcher Code in dem Build Output deiner App enthalten ist. Next Bundle Analyzer ist eine einfache Möglichkeit die JavaScript Bundles zu visualisieren und zu analysieren. + +- [@next/bundle-analyzer on npm](https://www.npmjs.com/package/@next/bundle-analyzer) diff --git a/www/src/pages/de/t3-collection.md b/www/src/pages/de/t3-collection.md new file mode 100644 index 0000000000..abfcb2eeea --- /dev/null +++ b/www/src/pages/de/t3-collection.md @@ -0,0 +1,38 @@ +--- +title: T3 Sammlung +description: Coole Open Source Projekte und Unternehmen, die den T3-Stack verwenden +layout: ../../layouts/docs.astro +lang: de +--- + +Du hast ein Projekt mit dem T3 Stack erstellt und möchtest es teilen? FĂŒg es der Liste hinzu! + +## Open Source Projekte die mit dem T3 Stack erstellt wurden + +| Beschreibung | Repo | Link | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| Create T3 Turbo - T3 Stack using Turborepo | [create-t3-turbo](https://github.com/t3-oss/create-t3-turbo) | [create-t3-turbo.vercel.app](https://create-t3-turbo.vercel.app/) | +| Zapdos - a QnA app for streamers | [pingdotgg/zapdos](https://github.com/pingdotgg/zapdos) | [ask.ping.gg](https://ask.ping.gg) | +| Shoutify - Free, open-source, self-hosted social media management | [techsquidtv/shoutify](https://github.com/TechSquidTV/Shoutify) | [shoutify.app](https://github.com/TechSquidTV/Shoutify) (coming soon) | +| Me3 - Describe yourself in 3 things and share with your friends. | [hnqg/me3](https://github.com/hnqg/me3) | [me3.hnqg.io](https://me3.hnqg.io) | +| Josh's personal site | [joshhyde9/portfolio](https://github.com/JoshHyde9/portfolio) | [joshhyde.me](https://joshhyde.me) | +| Cal.com - Scheduling infrastructure for absolutely everyone. | [calcom/cal.com](https://github.com/calcom/cal.com) | [cal.com](https://cal.com) | +| My FAQ Page - An FAQ Page generator | [ronanru/myfaq.page](https://github.com/ronanru/myfaq.page) | [MyFAQ.page](https://myfaq.page) | +| Tincy Pics - A tincy wincy image host | [mozzius/tincypics](https://github.com/mozzius/tincypics) | [tincy.pics](https://tincy.pics) | +| Ayanava's Guestbook | [AyanavaKarmakar/Guestbook](https://github.com/AyanavaKarmakar/Guestbook) | [guestbook.ayanavakarmakar.software](https://guestbook.ayanavakarmakar.software/) | +| Slug - URL Shortener | [pheralb/slug](https://github.com/pheralb/slug) | [slug.vercel.app](https://slug.vercel.app) | +| AI TTS Donations - FOSS AI Text To Speach service for Streamers. | [mmattDonk/AI-TTS-Donations](https://github.com/mmattDonk/AI-TTS-Donations) | [staging.solrock.mmattDonk.com](https://staging.solrock.mmattDonk.com) | +| The Doom | [moltivie/slug](https://github.com/Moltivie/the-t3-stack) | [the-t3-stack.vercel.app](https://the-t3-stack.vercel.app) | +| Railtrack | [noahflk/railtrack](https://github.com/noahflk/railtrack) | [railtrack.flk.li](https://railtrack.flk.li) | + +## Unternehmen die den T3 Stack verwenden + +Wir wĂŒrden gerne wissen, welche Unternehmen den T3 Stack fĂŒr ihre Apps verwenden. Nutzt ihr den T3 Stack und möchtet es teilen? FĂŒgt es der Liste hinzu! + +| Company | Link | +| ------- | ---------------------------------- | +| Ping.gg | [ping.gg](https://ping.gg) | +| Nexiona | [nexiona.com](https://nexiona.com) | +| Layer3 | [layer3.xyz](https://layer3.xyz) | + +_Du hast ein cooles Projekt mit dem T3 Stack erstellt? Erstelle einen [Pull Request](https://github.com/t3-oss/create-t3-app/tree/next/www/src/pages/de/t3-collection.md) und fĂŒge es hier hinzu!_ diff --git a/www/src/pages/de/usage/env-variables.md b/www/src/pages/de/usage/env-variables.md new file mode 100644 index 0000000000..31c82a27e1 --- /dev/null +++ b/www/src/pages/de/usage/env-variables.md @@ -0,0 +1,125 @@ +--- +title: Umgebungsvariablen +description: EinfĂŒhrung in create-t3-app +layout: ../../../layouts/docs.astro +lang: de +--- + +`create-t3-app` benutzt [Zod](https://github.com/colinhacks/zod) um deine Umgebungsvariablen zur Laufzeit _und_ zur Build Time zu validieren. Dazu werden zusĂ€tzliche Dateien im `env`-Verzeichnis bereitgestellt: + +📁 src/env + +┣ 📄 client.mjs + +┣ 📄 schema.mjs + +┣ 📄 server.mjs + +Der Inhalt dieser Dateien mag auf den ersten Blick beĂ€ngstigend sein, aber keine Sorge, es ist nicht so kompliziert wie es aussieht. Schauen wir uns diese nacheinander an und wie man zusĂ€tzliche Umgebungsvariablen hinzufĂŒgt. + +_TLDR; Wenn du eine neue Umgebungsvariable hinzufĂŒgen möchtest, musst du sie sowohl in deiner `.env` als auch in `env/schema.mjs` definieren._ + +## schema.mjs + +In dieser Datei finden die Änderungen statt. Sie enthĂ€lt zwei Schemas, eines fĂŒr Server-Umgebungsvariablen und eines fĂŒr Client-Umgebungsvariablen sowie ein `clientEnv`-Objekt. + +```ts:env/schema.mjs +export const serverSchema = z.object({ + // DATABASE_URL: z.string().url(), +}); + +export const clientSchema = z.object({ + // NEXT_PUBLIC_WS_KEY: z.string(), +}); + +export const clientEnv = { + // NEXT_PUBLIC_WS_KEY: process.env.NEXT_PUBLIC_WS_KEY, +}; +``` + +### Server Schema + +Definiere hier dein Server-Umgebungsvariablen-Schema. + +Stellt sicher, dass du hier keine Umgebungsvariablen mit dem `NEXT_PUBLIC`-PrĂ€fix verwendest. Die Validierung wird fehlschlagen, wenn du dies tust, um dir bei der Erkennung einer ungĂŒltigen Konfiguration zu helfen. + +### Client Schema + +Definiere hier dein Client-Umgebungsvariablen-Schema. + +Um sie dem Client zugĂ€nglich zu machen, musst du sie mit `NEXT_PUBLIC` prĂ€fixen. Die Validierung wird fehlschlagen, wenn du das nicht tust, um dir bei der Erkennung einer ungĂŒltigen Konfiguration zu helfen. + +### clientEnv Object + +In dieser Datei mĂŒssen wir auf die Werte vom `process.env`-Objekt zugreifen. + +Wir benötigen ein JavaScript-Objekt, welches wir durch das Zod-Schema validieren können und aufgrund der Art, wie Next.js Umgebungsvariablen behandelt. Da wir das `process.env`-Objekt nicht wie ein normales Objekt zerlegen ("destruct") können, mĂŒssen wir dies manuell machen. + +TypeScript wird dir helfen, sicherzustellen, dass du die SchlĂŒssel sowohl in `clientEnv` als auch in `clientSchema` eingegeben hast. + +```ts +// ❌ Das funktioniert nicht. Wir mĂŒssen es manuell zerlegen. +const schema = z.object({ + NEXT_PUBLIC_WS_KEY: z.string(), +}); + +const validated = schema.parse(process.env); +``` + +## server.mjs & client.mjs + +Hier findet die Validierung statt und die validierten Objekte werden exportiert. Diese Dateien solltest du nicht bearbeiten mĂŒssen. + +## Umgebungsvariablen verwenden + +Wenn du deine Umgebungsvariablen verwenden möchtest, kannst du sie aus `env/client.mjs` oder `env/server.mjs` importieren, je nachdem, wo du sie verwenden möchtest: + +```ts:pages/api/hello.ts +import { env } from "../../env/server.mjs"; + +// `env` ist vollstĂ€ndig typisiert und ermöglicht AutovervollstĂ€ndigung +const dbUrl = env.DATABASE_URL; +``` + +## .env.example + +Da die Standard `.env`-Datei nicht versioniert wird, haben wir ebenfalls eine `.env.example`-Datei beigefĂŒgt, in der du optional eine Kopie deiner `.env`-Datei mit entfernten geheimen Werten speichern kannst. Dies ist nicht erforderlich, aber wir empfehlen, das Beispiel auf dem neuesten Stand zu halten, um es fĂŒr Mitwirkende so einfach wie möglich zu machen, ihre Umgebung zum Laufen zu bekommen. + +## Umgebungsvariablen hinzufĂŒgen + +Um sicherzustellen, dass dein Build niemals ohne die Umgebungsvariablen abgeschlossen wird, die das Projekt benötigt, musst du neue Umgebungsvariablen an **zwei** Stellen hinzufĂŒgen: + +📄 `.env`: Schreibe hier deine Umgebungsvariable wie du es normalerweise in einer `.env`-Datei tun wĂŒrdest, z.B. `KEY=VALUE` + +📄 `schema.mjs`: FĂŒge die entsprechende Validierungslogik fĂŒr die Umgebungsvariable hinzu, indem du ein Zod-Schema definierst, z.B. `KEY: z.string()` + +Optional kannst du auch `.env.example` aktualisieren: + +📄 `.env.example`: FĂŒge deine Umgebungsvariable hinzu, aber vergiss nicht, den Wert zu entfernen, wenn dieser geheim ist, z.B. `KEY=VALUE` oder `KEY=` + +### Beispiel + +_Ich möchte meinen Twitter-API-Token als Server-Umgebungsvariable hinzufĂŒgen_ + +1. FĂŒge die Umgebungsvariable in die `.env`-Datei ein: + +``` +TWITTER_API_TOKEN=1234567890 +``` + +2. FĂŒge die Umgebungsvariable in `schema.mjs` ein: + +```ts +export const serverSchema = z.object({ + // ... + TWITTER_API_TOKEN: z.string(), +}); +``` + +_**Notiz:** Ein leerer String ist immer noch ein String und deshalb wird `z.string()` einen leeren String als gĂŒltigen Wert akzeptieren. Wenn du sicherstellen möchtest, dass die Umgebungsvariable nicht leer ist, kannst du `z.string().min(1)` verwenden._ + +3. optional: FĂŒge die Umgebungsvariable in `.env.example` ein, aber vergiss nicht, den Wert zu entfernen + +``` +TWITTER_API_TOKEN= +``` diff --git a/www/src/pages/de/usage/first-steps.md b/www/src/pages/de/usage/first-steps.md new file mode 100644 index 0000000000..cab7174f61 --- /dev/null +++ b/www/src/pages/de/usage/first-steps.md @@ -0,0 +1,36 @@ +--- +title: Erste Schritte +description: Erste Schritte mit deiner neuen T3 App +layout: ../../../layouts/docs.astro +lang: de +--- + +Du hast gerade eine neue T3 App erstellt und bist bereit loszulegen. Hier ist das Mindeste, um deine App zum Laufen zu bringen. + +## Datenbank + +Wenn deine App Prisma beinhaltet, musst du `npx prisma db push` aus dem Stammverzeichnis deiner App ausfĂŒhren. Dieser Befehl synchronisiert dein Prisma-Schema mit deiner Datenbank und generiert die TypeScript-Typen fĂŒr den Prisma-Client basierend auf deinem Schema. Beachte, dass du den TypeScript-Server nach dieser Aktion neu starten musst, damit die generierten Typen erkannt werden. + +## Authentifizierung + +Wenn deine App NextAuth.js beinhaltet, starten wir mit dem `DiscordProvider`. Dies ist einer der einfachsten Provider, die NextAuth.js anbietet, aber trotzdem ist noch ein wenig Einrichtung deinerseits erforderlich. + +Solltest du einen anderen Authentifizierungsanbieter bevorzugen, kannst du auch einen der [viele Anbieter](https://next-auth.js.org/providers/) verwenden, die NextAuth.js anbietet. + +1. Du benötigst einen Discord-Account. Registriere dich, wenn du noch keinen hast. +2. Navigiere zu https://discord.com/developers/applications und klicke in der oberen rechten Ecke auf "New Application". Gib deiner Anwendung einen Namen und stimme den Nutzungsbedingungen zu. +3. Sobald deine Anwendung erstellt wurde, navigiere zu "Settings → OAuth2 → General". +4. Kopiere die "Client ID" und fĂŒge sie in deine `.env` als `DISCORD_CLIENT_ID` ein. +5. Klick "Reset Secret", kopiere das neue Secret und fĂŒge den Wert in deine `.env` als `DISCORD_CLIENT_SECRET` ein. +6. Klick "Add Redirect" und gib `http://localhost:3000/api/auth/callback/discord` ein. + - FĂŒr den Produktivbetrieb mĂŒssen die vorherigen Schritte erneut verfolgt werden, um eine weitere Discord-Anwendung zu erstellen. Ersetze diesmal `http://localhost:3000` mit der URL, auf die du veröffentlichen möchtest. +7. Speicher die Änderungen. +8. Schreib das `NEXTAUTH_SECRET` in `.env`. WĂ€hrend der Entwicklung funktioniert jeder String. FĂŒr den Produktivbetrieb sollte ein Blick auf die Notiz in `.env` geworfen werden, um ein sicheres Secret zu erstellen. + +Du solltest dich nun anmelden können. + +## NĂ€chste Schritte + +- Wenn deine App tRPC beinhaltet, schau dir `src/pages/index.tsx` und `src/server/trpc/router/example.ts` an, um zu sehen, wie tRPC-Abfragen funktionieren. +- Schau dir die `create-t3-app`-Dokumentation an, sowie die Dokumentation der Pakete, die deine App beinhaltet. +- Tritt unserem [Discord](https://t3.gg/discord) bei und gib uns einen Stern auf [GitHub](https://github.com/t3-oss/create-t3-app)! :) diff --git a/www/src/pages/de/usage/next-auth.md b/www/src/pages/de/usage/next-auth.md new file mode 100644 index 0000000000..48ffa64c12 --- /dev/null +++ b/www/src/pages/de/usage/next-auth.md @@ -0,0 +1,176 @@ +--- +title: NextAuth.js +description: Verwendung von NextAuth.js +layout: ../../../layouts/docs.astro +lang: de +--- + +Wenn du ein Authentifizierungssystem in deiner Next.js-Anwendung haben möchtest, ist NextAuth.js eine ausgezeichnete Lösung, um die KomplexitĂ€t zu vermeiden, es selbst zu bauen. Es kommt mit einer umfangreichen Liste von Providern, um OAuth-Authentifizierung schnell hinzuzufĂŒgen und bietet Adapter fĂŒr viele Datenbanken und ORMs. + +## Context Provider + +In dem Einstiegspunkt deiner Anwendung, wirst du sehen, dass deine Anwendung von einem [SessionProvider](https://next-auth.js.org/getting-started/client#sessionprovider) umschlossen wird. + +```tsx:pages/_app.tsx + + + +``` + +Dieser Context-Provider ermöglicht es deiner Anwendung, auf die Daten der Session von ĂŒberall in deiner Anwendung zuzugreifen, ohne sie als Props weitergeben zu mĂŒssen: + +```tsx:pages/users/[id].tsx +import { useSession } from "next-auth/react"; + +const User = () => { + const { data: session } = useSession(); + + if (!session) { + // Behandlung des nicht authentifizierten Zustands, z. B. Rendern eines SignIn-Komponenten + return ; + } + + return

Welcome {session.user.name}!

; +}; +``` + +## EinfĂŒgen von `user.id` in die Session + +`create-t3-app` ist so konfiguriert, dass es den [session callback](https://next-auth.js.org/configuration/callbacks#session-callback) in der NextAuth.js-Konfiguration verwendet, um die ID des Benutzers im `session`-Objekt einzufĂŒgen. + +```ts:pages/api/auth/[...nextauth].ts +callbacks: { + session({ session, user }) { + if (session.user) { + session.user.id = user.id; + } + return session; + }, + }, +``` + +Dies ist mit einer Typdeklarationsdatei gekoppelt, um sicherzustellen, dass die `user.id` beim Zugriff auf das `session`-Objekt richtig getyped wird. Erfahre mehr ĂŒber [`"Module Augmentation"`](https://next-auth.js.org/getting-started/typescript#module-augmentation) in den Dokumentationen von NextAuth.js. + +```ts:types/next-auth.d.ts +import { DefaultSession } from "next-auth"; + +declare module "next-auth" { + interface Session { + user?: { + id: string; + } & DefaultSession["user"]; + } +} +``` + +Das gleiche Muster kann verwendet werden, um weitere Daten zum `session`-Objekt hinzuzufĂŒgen, wie z. B. ein `role`-Feld, aber dies **sollte nicht missbraucht werden, um sensible Daten auf dem Client zu speichern**. + +## Verwendung mit tRPC + +Wenn du NextAuth.js mit tRPC verwendest, kannst du wiederverwendbare, geschĂŒtzte Prozeduren mit [Middlewares](https://trpc.io/docs/v10/middlewares) erstellen. Dies ermöglicht es dir, Prozeduren zu erstellen, die nur von authentifizierten Benutzern zugĂ€nglich sind. `create-t3-app` stellt dir dies bereits zur VerfĂŒgung, so dass du problemlos auf das Session-Objekt innerhalb von authentifizierten Prozeduren zugreifen kannst. + +Dies geschieht in zwei Schritten: + +1. Greife auf die Session aus den Request-Headern zu, indem du die [`unstable_getServerSession`](https://next-auth.js.org/configuration/nextjs#unstable_getserversession)-Funktion verwendest. Mach dir keine Sorgen, diese Funktion lĂ€sst sich problemlos verwenden - der Name enthĂ€lt nur `unstable`, weil die API-Implementierung in Zukunft möglicherweise geĂ€ndert werden kann. Der Vorteil von `unstable_getServerSession` im Vergleich zu `getSession` ist, dass es eine serverseitige Funktion ist und unnötige Fetch-Aufrufe nicht ausgelöst werden. `create-t3-app` erstellt eine Hilfsfunktion, die diese eigenartige API abstrahiert. + +```ts:server/common/get-server-auth-session.ts +export const getServerAuthSession = async (ctx: { + req: GetServerSidePropsContext["req"]; + res: GetServerSidePropsContext["res"]; +}) => { + return await unstable_getServerSession(ctx.req, ctx.res, nextAuthOptions); +}; +``` + +Mit dieser Hilfsfunktion können wir die Session abgreifen und sie an den tRPC-Kontext ĂŒbergeben: + +```ts:server/trpc/context.ts +import { getServerAuthSession } from "../common/get-server-auth-session"; + +export const createContext = async (opts: CreateNextContextOptions) => { + const { req, res } = opts; + const session = await getServerAuthSession({ req, res }); + return await createContextInner({ + session, + }); +}; +``` + +2. Erstelle eine tRPC-Middleware, die ĂŒberprĂŒft, ob der Benutzer authentifiziert ist. Wir verwenden dann die Middleware in einer `protectedProcedure`. Jeder Aufrufer dieser Prozeduren muss authentifiziert sein, ansonsten wird eine Fehlermeldung geworfen, die vom Client entsprechend behandelt werden kann. + +```ts:server/trpc/trpc.ts +const isAuthed = t.middleware(({ ctx, next }) => { + if (!ctx.session || !ctx.session.user) { + throw new TRPCError({ code: "UNAUTHORIZED" }); + } + return next({ + ctx: { + // infers the `session` as non-nullable + session: { ...ctx.session, user: ctx.session.user }, + }, + }); +}); + +export const protectedProcedure = t.procedure.use(isAuthed); +``` + +Das `session`-Objekt ist eine minimale Darstellung des Benutzers und enthĂ€lt nur wenige Felder. Wenn du die `protectedProcedures` verwendest, hast du Zugriff auf die ID des Benutzers, die verwendet werden kann, um weitere Daten aus der Datenbank abzurufen. + +```ts:server/trpc/router/user.ts +const userRouter = router({ + me: protectedProcedure.query(({ ctx }) => { + const user = await prisma.user.findUnique({ + where: { + id: ctx.session.user.id, + }, + }); + return user; + }), +}); +``` + +## Verwendung mit Prisma + +Um NextAuth.js mit Prisma zu verwenden, ist eine Menge an [initialer Einrichtung](https://next-auth.js.org/adapters/models/) erforderlich. `create-t3-app` ĂŒbernimmt dies fĂŒr dich, und wenn du sowohl Prisma als auch NextAuth.js auswĂ€hlst, erhĂ€ltst du ein voll funktionsfĂ€higes Authentifizierungssystem mit allen erforderlichen Modellen, die vorkonfiguriert sind. Wir liefern deine App mit einem vorkonfigurierten Discord OAuth-Provider aus, den wir ausgewĂ€hlt haben, da es einer der einfachsten Provider zum starten ist - du musst nur deine Tokens in die `.env`-Datei eingeben und du kannst loslegen. Du kannst jedoch problemlos weitere Provider hinzufĂŒgen, indem du die [NextAuth.js-Dokumentation](https://next-auth.js.org/providers/) befolgst. Beachte, dass bestimmte Provider zusĂ€tzliche Felder zu bestimmten Modellen hinzufĂŒgen mĂŒssen. Wir empfehlen dir, die Dokumentation fĂŒr den Provider zu lesen, den du verwenden möchtest, um sicherzustellen, dass alle erforderlichen Felder vorhanden sind. + +### HinzufĂŒgen neuer Felder zu deinen Modellen + +Wenn du neue Felder zu einem der `User`, `Account`, `Session` oder `VerificationToken`-Modelle hinzufĂŒgst (du wirst wahrscheinlich nur das `User`-Modell anpassen mĂŒssen), musst du bedenken, dass der [Prisma-Adapter](https://next-auth.js.org/adapters/prisma) automatisch Felder zu diesen Modellen hinzufĂŒgt, wenn sich neue Benutzer anmelden und einloggen. Wenn du also neue Felder zu diesen Modellen hinzufĂŒgst, musst du Standardwerte fĂŒr sie bereitstellen, da der Adapter diese Felder nicht kennt. + +Wenn du zum Beispiel ein `role`-Feld zum `User`-Modell hinzufĂŒgen möchtest, musst du einen Standardwert fĂŒr das Feld bereitstellen. Dies wird durch HinzufĂŒgen eines `@default`-Werts zum `role`-Feld im `User`-Modell erreicht: + +```diff:prisma/schema.prisma ++ enum Role { ++ USER ++ ADMIN ++ } + + model User { + ... ++ role Role @default(USER) + } +``` + +## Verwendung mit Next.js-Middleware + +Die Verwendung von NextAuth.js mit Next.js-Middleware [erfordert die Verwendung der "JWT session strategy"](https://next-auth.js.org/configuration/nextjs#caveats) fĂŒr die Authentifizierung. Dies liegt daran, dass die Middleware nur auf die Sessioncookies zugreifen kann, wenn es sich um ein JWT handelt. StandardmĂ€ĂŸig ist `create-t3-app` so konfiguriert, dass die **default**-Datenbankstrategie verwendet wird, in Kombination mit Prisma als Datenbank-Adapter. + +## Einrichten des DiscordProviders (Standard) + +1. Navigiere zum [Abschnitt "Applications" im Discord Developer Portal](https://discord.com/developers/applications) und klicke auf "New Application" + +2. Im EinstellungsmenĂŒ wechsel zu "OAuth2 => General" + +- Kopier die Client-ID und fĂŒge sie in `DISCORD_CLIENT_ID` in `.env` ein. +- Unter Client Secret klickst du auf "Reset Secret" und kopierst diesen String in `DISCORD_CLIENT_SECRET` in `.env`. Sei vorsichtig, da du dieses Geheimnis nicht mehr sehen kannst und das ZurĂŒcksetzen dazu fĂŒhrt, dass das Bestehende ablĂ€uft. +- Klick auf "Add Redirect" und fĂŒge `/api/auth/callback/discord` ein (Beispiel fĂŒr die lokale Entwicklung: http://localhost:3000/api/auth/callback/discord) +- Speicher deine Änderungen +- Es ist möglich, aber wird nicht empfohlen, dass du die gleiche Discord-Anwendung fĂŒr die Entwicklung und die Produktion verwendest. Du könntest auch in Betracht ziehen [den Provider zu mocken](https://github.com/trpc/trpc/blob/main/examples/next-prisma-websockets-starter/src/pages/api/auth/%5B...nextauth%5D.ts) wĂ€hrend der Entwicklung. + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| -------------------------------- | --------------------------------------- | +| NextAuth.js Docs | https://next-auth.js.org/ | +| NextAuth.js GitHub | https://github.com/nextauthjs/next-auth | +| tRPC Kitchen Sink - mit NextAuth | https://kitchen-sink.trpc.io/next-auth | diff --git a/www/src/pages/de/usage/next-js.md b/www/src/pages/de/usage/next-js.md new file mode 100644 index 0000000000..e4e3f31593 --- /dev/null +++ b/www/src/pages/de/usage/next-js.md @@ -0,0 +1,36 @@ +--- +title: Next.js +description: Verwendung von Next.js +layout: ../../../layouts/docs.astro +lang: de +--- + +Next.js ist ein Backend-Framework fĂŒr deine React-Anwendungen. + +
+ +
+ +Schau dir [Theo's Next.js Conf talk](https://www.youtube.com/watch?v=W4UhNo3HAMw) um ein besseres VerstĂ€ndnis dafĂŒr zu bekommen, was Next.js ist und wie es funktioniert. + +## Warum sollte ich es benutzen? + +Wir lieben React. Es hat die Entwicklung von UIs zugĂ€nglich gemacht, auf eine Art und Weise, die wir uns vorher niemals hĂ€tten vorstellen können. Es kann Entwickler jedoch auch +auf einige holprige Pfade fĂŒhren. Next.js bietet einen leicht von Meinung geprĂ€gten, jedoch stark optimierten Ansatz, um Anwendungen mit React zu erstellen. Von Routing ĂŒber API-Definitionen bis hin zum Rendern von Bildern vertrauen wir darauf, dass Next.js Entwickler zu guten Entscheidungen fĂŒhrt. + +Next.js in Kombination mit [Vercel](https://vercel.com/) macht das Entwickeln und Bereitstellen von Webanwendungen einfacher als je zuvor. Deren extrem großzĂŒgiges Free-Tier und die extrem intuitive BenutzeroberflĂ€che ermöglicht es dir, deine Seite innerhalb weniger Klicks zu veröffentlichen. (Wir ❀ Vercel) + +## Get Static/Server Props + +Ein Hauptmerkmal von Next.js sind die FĂ€higkeiten zur Datenabfrage. Wir empfehlen dringend, die [offizielle Dokumentation](https://nextjs.org/docs/basic-features/data-fetching) zu lesen, um zu verstehen, wie die Funktionen funktionieren und wie sie sich unterscheiden. `getServerSideProps` wird in der Regel nur dann empfohlen, wenn es einen guten Grund dafĂŒr gibt, da es sich um einen blockierenden Aufruf handelt und die Seite verlangsamt. [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration) ist eine gute Alternative zu `getServerSideProps`, wenn die Daten dynamisch sind und inkrementell abgerufen werden können. + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| ------------------------------ | ---------------------------------- | +| Next.js Dokumentation | https://nextjs.org/docs | +| Next.js GitHub | https://github.com/vercel/next.js | +| Next.js Blog | https://nextjs.org/blog | +| Next.js Discord | https://nextjs.org/discord | +| Next.js Twitter | https://twitter.com/nextjs | +| Vercel/Next.js YouTube Channel | https://www.youtube.com/c/VercelHQ | diff --git a/www/src/pages/de/usage/prisma.md b/www/src/pages/de/usage/prisma.md new file mode 100644 index 0000000000..a0c3de4a7f --- /dev/null +++ b/www/src/pages/de/usage/prisma.md @@ -0,0 +1,77 @@ +--- +title: Prisma +description: Verwendung von Prisma +layout: ../../../layouts/docs.astro +lang: de +--- + +Prisma ist ein ORM fĂŒr TypeScript, welches dir erlaubt, dein Datenbankschema und Modelle in einer `schema.prisma` Datei zu definieren und dann einen typisierten Client zu generieren, welcher verwendet werden kann, um mit deiner Datenbank von deinem Backend aus zu interagieren. + +## Prisma Client + +Der Prisma Client wird in `/server/db/client.ts` instanziiert und als globale Variable exportiert (wie vom Prisma-Team als [best practice](https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices#problem) empfohlen). Wir stellen den Prisma Client ĂŒber den [Context](/de/usage/trpc#-servertrpccontextts) bereit und empfehlen den Client aus dem Context zu verwenden anstatt diesen in jeder Datei zu importieren. + +## Schema + +Du findest die Prisma Schema Datei in `/prisma/schema.prisma`. In dieser Datei definierst du dein Datenbankschema und deine Modelle. Diese Datei wird dafĂŒr verwendet den Prisma Client zu generieren. + +### Mit NextAuth.js + +Wenn du NextAuth.js zusammen mit Prisma auswĂ€hlst, wird die Schema Datei fĂŒr dich generiert und mit den empfohlenen Werten fĂŒr die `User`, `Session`, `Account` und `VerificationToken` Modelle vorbereitet, wie in der [NextAuth.js Dokumentation](https://next-auth.js.org/adapters/prisma) beschrieben. + +## Standard Datenbank + +Die Standard Datenbank ist eine SQLite Datenbank, welche fĂŒr die Entwicklung und das schnelle Erstellen eines Proof-of-Concepts sehr gut geeignet ist. FĂŒr den Produktivbetrieb wird dies jedoch nicht empfohlen. Du kannst die Datenbank Ă€ndern, indem du den `provider` im `datasource` Block auf `postgresql` oder `mysql` Ă€nderst und dann die Verbindungs-URL in den Umgebungsvariablen anpasst, um auf deine Datenbank zu zeigen. + +## Datenbank befĂŒllen ("Seeding") + +["Seeding"](https://www.prisma.io/docs/guides/database/seed-database) ist eine gute Möglichkeit, um deine Datenbank mit Testdaten zu befĂŒllen. Um das BefĂŒllen zu konfigurieren, musst du eine `seed.ts` Datei im `/prisma` Verzeichnis erstellen und dann ein `seed` Script in deine `package.json` Datei einfĂŒgen. Du benötigst ebenfalls einen TypeScript Runner, der das Seed-Script ausfĂŒhren kann. Wir empfehlen [tsx](https://github.com/esbuild-kit/tsx), welcher ein sehr performanter TypeScript Runner ist, der esbuild verwendet und keine ESM-Konfiguration benötigt. `ts-node` oder andere Runner funktionieren ebenfalls. + +```jsonc:package.json +{ + "scripts": { + "db-seed": "NODE_ENV=development prisma db seed" + }, + "prisma": { + "seed": "tsx prisma/seed.ts" + } +} +``` + +```ts:prisma/seed.ts +import { prisma } from "../src/server/db/client"; + +async function main() { + const id = "cl9ebqhxk00003b600tymydho"; + await prisma.example.upsert({ + where: { + id, + }, + create: { + id, + }, + update: {}, + }); +} + +main() + .then(async () => { + await prisma.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await prisma.$disconnect(); + process.exit(1); + }); +``` + +Anschließend kannst du einfach `pnpm db-seed` (oder `npm`/`yarn`) ausfĂŒhren, um deine Datenbank zu befĂŒllen. + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Prisma Docs | https://www.prisma.io/docs/ | +| Prisma GitHub | https://github.com/prisma/prisma | +| NextAuth.JS Prisma Adapter | https://next-auth.js.org/adapters/prisma | +| Planetscale Connection Guide | https://www.prisma.io/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases/connect-your-database-typescript-planetscale | diff --git a/www/src/pages/de/usage/tailwind.md b/www/src/pages/de/usage/tailwind.md new file mode 100644 index 0000000000..ed2a052c43 --- /dev/null +++ b/www/src/pages/de/usage/tailwind.md @@ -0,0 +1,96 @@ +--- +title: Tailwind CSS +description: Verwendung von TailwindCSS +layout: ../../../layouts/docs.astro +lang: de +--- + +## Was ist Tailwind CSS? + +Tailwind CSS ist ein kleines, [utility first](https://tailwindcss.com/docs/utility-first) CSS-Framework fĂŒr die Erstellung benutzerdefinierter Designs, ohne dass zwischen verschiedenen Kontexten gewechselt werden muss. Es ist ein reines CSS-Framework und bietet keine vorgefertigten Komponenten oder Logik. Ebenfalls ergibt sich [eine sehr unterschiedliche Reihe von Vorteilen](https://www.youtube.com/watch?v=CQuTF-bkOgc) im Vergleich zu einer Komponentenbibliothek wie Material UI. + +Es ermöglicht CSS unglaublich einfach und schnell zu schreiben, wie im folgenden Beispiel gezeigt: + +Altes CSS: + +1. Schreibe CSS (oft in einer separaten Datei) + +```css +.my-class { + display: flex; + flex-direction: column; + justify-content: center; + align-items: center; + background-color: #fff; + border: 1px solid #e2e8f0; + border-radius: 0.25rem; + padding: 1rem; +} +``` + +2. Importiere CSS in deine Komponente + +```jsx +import "./my-class.css"; +``` + +3. FĂŒge die Klasse deinem HTML hinzu + +```html +
...
+``` + +Äquivalent in Tailwind: + +1. FÜge die Klasse lediglich deinem HTML hinzu + +```html +
+ ... +
+``` + +In Kombination mit React-Komponenten ist es extrem mĂ€chtig, um schnell BenutzeroberflĂ€chen zu erstellen. + +Tailwind CSS hat ein sehr schönes integriertes Design-System, dass mit einer sorgfĂ€ltig ausgewĂ€hlten Farbpalette, GrĂ¶ĂŸenvorgaben fĂŒr Styles wie width/height und padding/margin sowie Media-Breakpoints fĂŒr responsive Layouts ausgeliefert wird. Dieses Design-System kann angepasst und erweitert werden, um die exakte Toolbox an Styles zu erstellen, die dein Projekt benötigt. + +
+ +
+ +Tru Narla, besser bekannt als [mewtru](https://twitter.com/trunarla), hat eine großartige PrĂ€sentation ĂŒber [das Erstellen eines Design-Systems mit Tailwind CSS](https://www.youtube.com/watch?v=T-Zv73yZ_QI) gehalten. + +## Verwendung + +Stell sicher, dass du Editor-Plugins fĂŒr Tailwind installiert hast, um die Verwendung von Tailwind zu verbessern. + +### Erweiterungen und Plugins + +- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) +- [JetBrains Integration](https://www.jetbrains.com/help/webstorm/tailwind-css.html#ws_css_tailwind_install) +- [Neovim LSP](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#tailwindcss) + +### Formatierung + +Tailwind CSS Klassen können schnell unĂŒbersichtlich werden, daher ist ein Formatter fĂŒr die Klassen ein Muss. [Tailwind CSS Prettier Plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) sortiert die Klassen in der [empfohlenen Reihenfolge](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier#how-classes-are-sorted), sodass die Klassen mit dem ausgegebenen CSS-Bundle ĂŒbereinstimmen. Wenn du Tailwind in der CLI auswĂ€hlst, installieren und konfigurieren wir dies fĂŒr dich. + +### Bedingte Anwendung von Klassen + +Das HinzufĂŒgen von Klassen unter Bedingungen mit "ternaries" kann sehr unĂŒbersichtlich und schwer zu lesen werden. Diese Pakete helfen bei der Organisation deiner Klassen, wenn du bedingte Logik verwendest. + +- [clsx](https://github.com/lukeed/clsx) +- [classnames](https://github.com/JedWatson/classnames) + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| ---------------------------- | -------------------------------------------------------- | +| Tailwind Docs | https://tailwindcss.com/docs/editor-setup/ | +| Tailwind Cheat Sheet | https://nerdcave.com/tailwind-cheat-sheet/ | +| awesome-tailwindcss | https://github.com/aniftyco/awesome-tailwindcss/ | +| Tailwind Community | https://github.com/tailwindlabs/tailwindcss/discussions/ | +| Tailwind Discord Server | https://tailwindcss.com/discord/ | +| TailwindLabs Youtube Channel | https://www.youtube.com/tailwindlabs/ | +| Tailwind Playground | https://play.tailwindcss.com/ | diff --git a/www/src/pages/de/usage/trpc.md b/www/src/pages/de/usage/trpc.md new file mode 100644 index 0000000000..3e29eaae93 --- /dev/null +++ b/www/src/pages/de/usage/trpc.md @@ -0,0 +1,334 @@ +--- +title: tRPC +description: Verwendung von tRPC +layout: ../../../layouts/docs.astro +lang: de +--- + +tRPC ermöglicht es uns, end-to-end typisierte APIs zu schreiben, komplett ohne Code-Generation oder Laufzeit-Bloat. +Es nutzt die großartige Inferenz von TypeScript, um die Typdefinitionen vom API-Routers zu inferieren und erlaubt es dir, deine API-Prozeduren aus dem Frontend heraus mit voller Typsicherheit und AutovervollstĂ€ndigung aufzurufen. Wenn du tRPC verwendest, fĂŒhlen sich Front- und Backend nĂ€her zusammen als je zuvor, was zu einer herausragenden Entwicklerzufriedenheit fĂŒhrt. + +
+
+

+ I built tRPC to allow people to move faster by removing the need of a traditional API-layer, while still having confidence that our apps won't break as we rapidly iterate. +

+
+ + Avatar of @alexdotjs +
+ Alex - creator of tRPC + + @alexdotjs + +
+ +
+ +## Dateien + +tRPC benötigt eine Menge Boilerplate, die `create-t3-app` fĂŒr dich einrichtet. Lass uns die Dateien durchgehen, die erstellt werden: + +### 📄 `pages/api/trpc/[trpc].ts` + +Dies ist der Einstiegspunkt fĂŒr deine API und stellt den tRPC-Router zur VerfĂŒgung. Normalerweise wirst du dich in dieser Datei nicht sehr oft aufhalten. +Wenn du aber z. B. eine Middleware fĂŒr CORS oder Ă€hnliches benötigst, ist es hilfreich zu wissen, dass die exportierte `createNextApiHandler` ein [Next.js API-Handler](https://nextjs.org/docs/api-routes/introduction) ist, der ein [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) und [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response?retiredLocale=sv-SE) Objekt entgegennimmt. Dies bedeutet, dass du `createNextApiHandler` mit irgendeiner Middleware umschließen kannst. Siehe unten fĂŒr ein [Beispiel](#enabling-cors) zum HinzufĂŒgen von CORS. + +### 📄 `server/trpc/context.ts` + +In dieser Datei definierst du den Kontext, welcher an deine tRPC-Prozeduren ĂŒbergeben wird. Der Kontext besteht aus Daten, auf die alle deine tRPC-Prozeduren Zugriff haben und ist ein guter Ort, um Dinge wie Datenbankverbindungen, Authentifizierungsdaten usw. zu speichern. In `create-t3-app` verwenden wir zwei Funktionen, um einen Teil des Kontexts zu verwenden, wenn wir keinen Zugriff auf das Request-Objekt haben. + +- `createContextInner`: Hier definierst du den Kontext, der nicht von der Anfrage abhĂ€ngt, z. B. deine Datenbankverbindung. Du kannst diese Funktion fĂŒr [Integrationstests](#sample-integration-test) oder [ssg-helpers](https://trpc.io/docs/v10/ssg-helpers) verwenden, bei denen du kein "Request"-Objekt hast. + +- `createContext`: Hier definierst du den Kontext, der von der Anfrage abhĂ€ngt, z. B. die Sitzung des Benutzers. Du fragst die Sitzung mit dem `opts.req`-Objekt ab und gibst sie dann an die `createContextInner`-Funktion weiter, um den endgĂŒltigen Kontext zu erstellen. + +### 📄 `server/trpc/trpc.ts` + +Hier wird tRPC initialisiert und wieder verwendbare [Prozeduren](https://trpc.io/docs/v10/procedures) und [Middlewares](https://trpc.io/docs/v10/middlewares) definiert. Nach Konvention solltest du das gesamte `t`-Objekt nicht exportieren, sondern stattdessen wieder verwendbare Prozeduren und Middlewares erstellen und diese exportieren. + +Du hast sicherlich bemerkt, dass wir `superjson` als [data transformer](https://trpc.io/docs/v10/data-transformers) verwenden. Dies sorgt dafĂŒr, dass deine Datentypen erhalten bleiben, wenn sie den Client erreichen, sodass z. B. ein `Date`-Objekt an den Client gesendet wird, der ein `Date` zurĂŒckgibt und nicht ein String, so wie es bei den meisten APIs der Fall ist. + +### 📄 `server/trpc/router/*.ts` + +Hier definierst du die Routen und Prozeduren deiner API. Nach Konvention erstellst du [separate Router](https://trpc.io/docs/v10/router) fĂŒr zusammengehörige Prozeduren und dann [verbindest ("merge")](https://trpc.io/docs/v10/merging-routers) du alle in einen einzigen App-Router in `server/trpc/router/_app.ts`. + +### 📄 `utils/trpc.ts` + +Dies ist der Einstiegspunkt fĂŒr tRPC auf der Clientseite. Hier importierst du die **Typdefinition** des Routers und erstellst deinen tRPC-Client zusammen mit den react-query-Hooks. Da wir `superjson` als unseren Daten-Transformer auf der Serverseite aktiviert haben, mĂŒssen wir ihn auch auf der Clientseite aktivieren. Dies liegt daran, dass die serialisierten Daten vom Server auf der Clientseite deserialisiert werden. + +You'll define your tRPC [links](https://trpc.io/docs/v10/links) here, which determines the request flow from the client to the server. We use the "default" [`httpBatchLink`](https://trpc.io/docs/v10/links/httpBatchLink) which enables [request batching](https://cloud.google.com/compute/docs/api/how-tos/batch), as well as a [`loggerLink`](https://trpc.io/docs/v10/links/loggerLink) which outputs useful request logs during development. + +Ebenfalls definierst du hier die tRPC [links](https://trpc.io/docs/v10/links) hier, die den Anfrageablauf ("Request flow") vom Client zum Server abbilden. Wir verwenden den "Standard" [`httpBatchLink`](https://trpc.io/docs/v10/links/httpBatchLink), welcher [request batching](https://cloud.google.com/compute/docs/api/how-tos/batch) ermöglicht, sowie einen [`loggerLink`](https://trpc.io/docs/v10/links/loggerLink), der nĂŒtzliche Logs wĂ€hrend der Entwicklung ausgibt. + +Zuletzt exportieren wir einen [Hilfstyp](https://trpc.io/docs/v10/infer-types#additional-dx-helper-type), den du verwenden kannst, um deine Typen auf der Clientseite abzuleiten. + +## Wie verwende ich tRPC? + +
+ +
+ +tRPC Mitwirkender [trashh_dev](https://twitter.com/trashh_dev) hat [einen tollen Vortrag auf der Next.js Conf](https://www.youtube.com/watch?v=2LYM8gf184U) ĂŒber tRPC gehalten. Wir empfehlen dir, ihn anzusehen, wenn du ihn noch nicht gesehen hast. + +With tRPC, you write TypeScript functions on your backend, and then call them from your frontend. A simple tRPC procedure could look like this: + +Mit tRPC schreibst du TypeScript-Funktionen in deinem Backend und rufst sie dann von deinem Frontend aus auf. Eine einfache tRPC-Prozedur könnte so aussehen: + +```ts:server/trpc/router/user.ts +const userRouter = t.router({ + getById: t.procedure.input(z.string()).query(({ ctx, input }) => { + return ctx.prisma.user.findFirst({ + where: { + id: input, + }, + }); + }), +}); +``` + +Dies ist tRPC-Prozedur (Äquivalent zu einem Routen-Handler in einem traditionellen Backend), die zuerst den Input mittels Zod validiert (welches die gleiche Validierungs-Bibliothek ist, die wir fĂŒr [Environment-Variables](./env-variables) verwenden) - in diesem Fall wird sichergestellt, dass der Input ein String ist. Wenn der Input kein String ist, wird ein detailierter Fehler zurĂŒckgesendet. + +Nach dem Inputaufruf folgt eine Resolver-Funktion, die entweder eine [query](https://trpc.io/docs/v10/react-queries), [mutation](https://trpc.io/docs/v10/react-mutations) oder eine [subscription](https://trpc.io/docs/v10/subscriptions) sein kann. In unserem Beispiel ruft die Resolver-Funktion unsere Datenbank mit unserem [prisma](./prisma)-Client auf und gibt den Benutzer zurĂŒck, dessen `id` mit der ĂŒbereinstimmt, die wir ĂŒbergeben haben. + +Du definierst deine Prozeduren in `routers` welche eine Sammlung von zusammengehörigen Prozeduren innerhalb eines gemeinsamen Namespaces darstellen. Du könntest einen Router fĂŒr `users`, einen fĂŒr `posts` und einen fĂŒr `messages` haben. Diese Router können dann in einen einzigen, zentralen `appRouter` zusammengefĂŒhrt werden: + +```ts:server/trpc/router/_app.ts +const appRouter = t.router({ + users: userRouter, + posts: postRouter, + messages: messageRouter, +}); + +export type AppRouter = typeof appRouter; +``` + +Beachte dass wir nur unsere Router-Typdefinitionen exportieren mĂŒssen, was bedeutet, dass wir nie Server-Code in unserem Client importieren. + +Lass uns nun die Prozedur auf unserem Frontend aufrufen. tRPC stellt einen Wrapper fĂŒr `@tanstack/react-query` bereit, der es dir ermöglicht, die volle StĂ€rke dieser Hooks zu nutzen, aber mit dem zusĂ€tzlichen Vorteil, dass deine API-Aufrufe typisiert sind. Wir können unsere Prozeduren von unserem Frontend aus wie folgt aufrufen: + +```tsx:pages/users/[id].tsx +import { useRouter } from "next/router"; + +const UserPage = () => { + const { query } = useRouter(); + const userQuery = trpc.user.getById.useQuery(query.id); + + return ( +
+

{userQuery.data?.name}

+
+ ); +}; +``` + +Du wirst sofort bemerken, wie gut die AutovervollstĂ€ndigung und die Typsicherheit ist. Sobald du `trpc.` schreibst werden deine Router in der AutovervollstĂ€ndigung angezeigt. +Wenn du nun einen Router auswĂ€hlst, werden auch seine Prozeduren angezeigt. Wenn dein Input nicht mit dem Validator ĂŒbereinstimmt, den du im Backend definiert hast, erhĂ€ltst du einen TypeScript-Fehler. + +## Wie rufe ich meine API von extern auf? + +Mit regulĂ€ren APIs kannst du deine Endpunkte mit jedem HTTP-Client wie `curl`, `Postman`, `fetch` oder direkt aus deinem Browser aufrufen. Mit tRPC ist es ein bisschen anders. Wenn du deine Prozeduren ohne den tRPC-Client aufrufen möchtest, gibt es zwei empfohlene Möglichkeiten: + +### Eine einzelne Prozedur extern verfĂŒgbar machen + +Wenn du eine einzelne Prozedur extern verfĂŒgbar machen möchtest, bist du auf [serverseitige Aufrufe](https://trpc.io/docs/v10/server-side-calls) angewiesen. Das wĂŒrde es dir ermöglichen, einen normalen Next.js-API-Endpunkt zu erstellen, aber die Resolver-Teil deiner tRPC-Prozedur wiederverwenden. + +```ts:pages/api/users/[id].ts +import type { NextApiRequest, NextApiResponse } from "next"; +import { appRouter } from "../../../server/trpc/router/_app"; +import { createContext } from "../../../server/trpc/context"; + +const userByIdHandler = async (req: NextApiRequest, res: NextApiResponse) => { + // Create context and caller + const ctx = await createContext({ req, res }); + const caller = appRouter.createCaller(ctx); + try { + const { id } = req.query; + const user = await caller.user.getById(id); + res.status(200).json(user); + } catch (cause) { + if (cause instanceof TRPCError) { + // An error from tRPC occured + const httpCode = getHTTPStatusCodeFromError(cause); + return res.status(httpCode).json(cause); + } + // Another error occured + console.error(cause); + res.status(500).json({ message: "Internal server error" }); + } +}; + +export default userByIdHandler; +``` + +### Alle Prozeduren als REST-Endpunkt verfĂŒgbar machen + +Wenn du jede einzelne Prozedur extern verfĂŒgbar machen möchtest, schau dir das von der Community erstellte Plugin [trpc-openapi](https://github.com/jlalmes/trpc-openapi/tree/master) an. Hiermit kannst du aus deinem tRPC-Router eine OpenAPI-konforme REST-API generieren, indem du zusĂ€tzliche Metadaten zu deinen Prozeduren hinzufĂŒgst. + +### Es sind lediglich HTTP-Anfragen + +tRPC kommuniziert ĂŒber HTTP, so dass es auch möglich ist, deine tRPC-Prozeduren mit "normalen" HTTP-Anfragen aufzurufen. Die Syntax kann jedoch aufgrund des [RPC-Protokolls](https://trpc.io/docs/v10/rpc), das tRPC verwendet, umstĂ€ndlich sein. Wenn du neugierig bist, dann schau im Netzwerktab vom deinem Browser wie die tRPC Anfragen und Antworten aussehen. Wir empfehlen dies jedoch nur zum Lernzweck und wĂŒrden dir raten, in der Regel eine der oben genannten Lösungen zu verwenden. + +## Vergleich zu einem Next.js API-Endpunkt + +Let's compare a Next.js API endpoint to a tRPC procedure. Let's say we want to fetch a user object from our database and return it to the frontend. We could write a Next.js API endpoint like this: + +Lass uns nun einen Next.js-API-Endpunkt mit einer tRPC-Prozedur vergleichen. Gehen wir davon aus, dass wir ein Benutzerobjekt aus unserer Datenbank abrufen möchten und es dann an das Frontend zurĂŒckgeben. Wir könnten einen Next.js-API-Endpunkt wie folgt schreiben: + +```ts:pages/api/users/[id].ts +import type { NextApiRequest, NextApiResponse } from "next"; +import { prisma } from "../../../server/db/client"; + +const userByIdHandler = async (req: NextApiRequest, res: NextApiResponse) => { + if (req.method !== "GET") { + return res.status(405).end(); + } + + const { id } = req.query; + + if (!id || typeof id !== "string") { + return res.status(400).json({ error: "Invalid id" }); + } + + const examples = await prisma.example.findFirst({ + where: { + id, + }, + }); + + res.status(200).json(examples); +}; + +export default userByIdHandler; +``` + +```ts:pages/users/[id].tsx +import { useState, useEffect } from "react"; +import { useRouter } from "next/router"; + +const UserPage = () => { + const router = useRouter(); + const { id } = router.query; + + const [user, setUser] = useState(null); + useEffect(() => { + fetch(`/api/user/${id}`) + .then((res) => res.json()) + .then((data) => setUser(data)); + }, [id]); +}; +``` + +Wenn wir das nun mit dem tRPC Beispiel von davor vergleichen, lassen sich folgende Vorteile von tRPC erkennen: + +- Anstatt fĂŒr jede Route eine URL anzugeben, was bei Änderungen an der Struktur des Projekts zu Fehlern fĂŒhren kann, ist dein gesamter Router ein Objekt mit AutovervollstĂ€ndigung. +- Du musst nicht validieren, welche HTTP-Methode verwendet wurde. +- You don’t need to validate that the request query or body contains the correct data in the procedure, because Zod takes care of this. +- Du musst nicht validieren, ob die "request query" der "request body" die richtigen Daten enthĂ€lt, da Zod sich darum kĂŒmmert. +- Anstatt eine Antwort zu erstellen, kannst du Fehler werfen und einen Wert oder ein Objekt zurĂŒckgeben, wie du es in jeder anderen TypeScript-Funktion tun wĂŒrdest. +- Das Aufrufen der Prozedur auf dem Frontend bietet AutovervollstĂ€ndigung und Typsicherheit. + +## NĂŒtzliche Snippets + +Hier sind einige Snippets, die vielleicht nĂŒtzlich sein könnten. + +### CORS aktivieren + +Wenn du deine API von einer anderen Domain konsumieren musst, zum Beispiel in einem Monorepo, das eine React Native App enthĂ€lt, musst du möglicherweise CORS aktivieren: + +```ts:pages/api/trpc/[trpc].ts +import type { NextApiRequest, NextApiResponse } from "next"; +import { createNextApiHandler } from "@trpc/server/adapters/next"; +import { appRouter } from "~/server/trpc/router/_app"; +import { createContext } from "~/server/trpc/context"; +import cors from "nextjs-cors"; + +const handler = async (req: NextApiRequest, res: NextApiResponse) => { + // Enable cors + await cors(req, res); + + // Create and call the tRPC handler + return createNextApiHandler({ + router: appRouter, + createContext, + })(req, res); +}; + +export default handler; +``` + +### Optimistische Updates + +Optimitische Updates sind Updates, die wir vornehmen, bevor die API-Anfrage abgeschlossen ist. Dies bietet dem Benutzer eine bessere Erfahrung, da er nicht darauf warten muss, dass die API-Anfrage abgeschlossen ist, bevor die BenutzeroberflĂ€che das Ergebnis seiner Aktion widerspiegelt. Apps, die die Richtigkeit der Daten sehr schĂ€tzen, sollten jedoch Optimistische Updates vermeiden, da sie nicht die "wahren" Daten des Backends widerspiegeln. Du kannst mehr darĂŒber in der [React Query Dokumentation](https://tanstack.com/query/v4/docs/guides/optimistic-updates) lesen. + +```tsx +const MyComponent = () => { + const listPostQuery = trpc.post.list.useQuery(); + + const utils = trpc.useContext(); + const postCreate = trpc.post.create.useMutation({ + async onMutate(newPost) { + // Cancel outgoing fetches (so they don't overwrite our optimistic update) + await utils.post.list.cancel(); + + // Get the data from the queryCache + const prevData = utils.post.list.getData(); + + // Optimistically update the data with our new post + utils.post.list.setData(undefined, (old) => [...old, newPost]); + + // Return the previous data so we can revert if something goes wrong + return { prevData }; + }, + onError(err, newPost, ctx) { + // If the mutation fails, use the context-value from onMutate + utils.post.list.setData(undefined, ctx.prevData); + }, + onSettled() { + // Sync with server once mutation has settled + utils.post.list.invalidate(); + }, + }); +}; +``` + +### Beispiel Integrationstest + +Hier ist ein Beispiel fĂŒr einen Integrationstest, der [Vitest](https://vitest.dev) verwendet, um zu ĂŒberprĂŒfen, ob dein tRPC-Router wie erwartet funktioniert, der Eingabe-Parser den richtigen Typ ableitet und die zurĂŒckgegebenen Daten mit dem erwarteten Ergebnis ĂŒbereinstimmen. + +```ts +import { type inferProcedureInput } from "@trpc/server"; +import { createContextInner } from "~/server/router/context"; +import { appRouter, type AppRouter } from "~/server/router/_app"; +import { expect, test } from "vitest"; + +test("example router", async () => { + const ctx = await createContextInner({ session: null }); + const caller = appRouter.createCaller(ctx); + + type Input = inferProcedureInput; + const input: Input = { + text: "test", + }; + + const example = await caller.example.hello(input); + + expect(example).toMatchObject({ greeting: "Hello test" }); +}); +``` + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| --------------------- | ------------------------------------------------------- | +| tRPC Docs | https://www.trpc.io | +| Einige tRPC Beispiele | https://github.com/trpc/trpc/tree/next/examples | +| React Query Docs | https://tanstack.com/query/v4/docs/adapters/react-query | diff --git a/www/src/pages/de/usage/typescript.md b/www/src/pages/de/usage/typescript.md new file mode 100644 index 0000000000..85703a7ff3 --- /dev/null +++ b/www/src/pages/de/usage/typescript.md @@ -0,0 +1,67 @@ +--- +title: TypeScript +description: Verwendung von TypeScript +layout: ../../../layouts/docs.astro +lang: de +--- + +
+
+

+ Build safety nets, not guard rails +

+
+ + Avatar of @t3dotgg +
+ Theo - creator of the T3 Stack + + @t3dotgg + +
+ +
+ +UnabhĂ€ngig davon, ob du ein neuer oder erfahrener Entwickler bist, denken wir, dass TypeScript ein Muss ist. Es kann auf den ersten Blick einschĂŒchternd wirken, aber wie bei vielen Tools ist es etwas, das man nicht missen möchte, nachdem man angefangen hat, es zu benutzen. + +Es bietet Live-Feedback wĂ€hrend du deinen Code schreibst. Die erwarteten Datentypen werden definiert und entweder erhalten wir hilfreiche AutovervollstĂ€ndigung in unserem Code-Editor oder es wird uns mit roten Unterstrichen auf ein Problem aufmerksam gemacht z.B. wenn wir versuchen auf eine Eigenschaft zuzugreifen, die nicht existiert oder wenn wir versuchen einen Wert eines falschen Typs zu ĂŒbergeben. Dadurch können wir Fehler frĂŒhzeitig erkennen und beheben ohne erst im Nachhinein debuggen zu mĂŒssen. + +Es ist wohlmöglich das Werkzeug, das Entwicklern die grĂ¶ĂŸte ProduktivitĂ€t bietet; es bietet Dokumentation des geschriebenen Codes direkt in deinem Editor und gibt dir sofortiges Feedback, wenn du unweigerlich Fehler machst. Das ist absolut unbezahlbar. + +## Type Inference + +WĂ€hrend viele neue TypeScript Entwickler sich mit dem _Schreiben_ von TypeScript beschĂ€ftigt, bieten viele der Vorteile von TypeScript gar nicht die Notwendigkeit, deinen Code zu Ă€ndern. Insbesondere die Typinferenz. Typinferenz bedeutet, dass wenn etwas typisiert ist, sich dieser Typ durch die gesamte Anwendung bewegt, ohne dass dieser in anderen Teilen der Anwendung erneut deklariert werden muss. Das bedeutet, dass z.B. wenn du die Typen der Argumente einer Funktion definiert hast, der Rest der Funktion in der Regel typesafe ist, ohne dass zusĂ€tzlicher TypeScript-spezifischer Code erforderlich ist. Entwickler von Bibliotheken investieren viel Arbeit in die Wartung der Typen ihrer Bibliotheken, was bedeutet, dass wir als Anwender von der Inferenz und der integrierten Dokumentation in deinem Code-Editor profitieren können, die durch diese Typen bereitgestellt werden. + +
+ +
+ +Schau dir das Video von Theo an, warum [du TypeScript wohlmöglich falsch benutzt](https://www.youtube.com/watch?v=RmGHnYUqQ4k). + +## MĂ€chtige Verwendung von Typinferenz + +### Zod + +[Zod](https://github.com/colinhacks/zod) ist eine Schema-Validierungs-Bibliothek, die auf TypeScript aufbaut. Schreibe ein Schema, das die einzige Quelle der Wahrheit ("single source of truth") fĂŒr deine Daten darstellt, und Zod wird sicherstellen, dass deine Daten ĂŒberall in deiner Anwendung gĂŒltig sind. Sogar ĂŒber Netzwerkgrenzen und externe APIs hinweg. + +### Tanstack Query + +[Tanstack Query](https://tanstack.com/query/v4/) bietet dir deklarative, immer aktuelle, automatisch verwaltete "Queries" und "Mutations", die direkt die Entwickler- und Benutzerzufriedenheit verbessern. + +## NĂŒtzliche Ressourcen + +| Resource | Link | +| --------------------------------------------------------- | ----------------------------------------------------------------- | +| TypeScript Handbook | https://www.typescriptlang.org/docs/handbook/ | +| Beginners TypeScript Tutorial | https://github.com/total-typescript/beginners-typescript-tutorial | +| Type Challenges | https://github.com/type-challenges/type-challenges | +| Rodney Mullen of TypeScript (Matt Pocock) Youtube Channel | https://www.youtube.com/c/MattPocockUk/videos | diff --git a/www/src/pages/de/why.md b/www/src/pages/de/why.md new file mode 100644 index 0000000000..9dfb392db0 --- /dev/null +++ b/www/src/pages/de/why.md @@ -0,0 +1,52 @@ +--- +title: Warum CT3A? +description: Warum du Create T3 App fĂŒr dein nĂ€chstes Projekt wĂ€hlen solltest +layout: ../../layouts/docs.astro +lang: de +--- + +Wir haben mit der Entwicklung create-t3-app begonnen, weil [Theo](https://twitter.com/t3dotgg) keine Vorlage seiner Lieblingstechnologien erstellen wollte. Inspiriert von create-next-app, [Astro's CLI](https://astro.build) und einer allgemeinen Liebe zur Typsicherheit hat das create-t3-app-Team hart gearbeitet, um den bestmöglichen Ausgangspunkt fĂŒr neue T3 Stack-Projekte zu schaffen. + +Wenn du daran interessiert bist Next.js auf eine typsichere Weise zu verwenden, ist dies der richtige Ort um zu beginnen. Wenn du dich dafĂŒr interessierst, warum wir welche spezifischen Technologie-Entscheidungen getroffen haben, lies weiter :) + +## Warum TypeScript? + +JavaScript ist schwer. Warum sollte man noch mehr Regeln hinzufĂŒgen? + +Wir glauben fest daran, dass das Erlebnis, das TypeScript bietet, dir dabei helfen wird ein besserer Entwickler zu werden. +Es bietet Live-Feedback wĂ€hrend du deinen Code schreibst. Die erwarteten Datentypen werden definiert und entweder erhalten wir hilfreiche AutovervollstĂ€ndigung in unserem Code-Editor oder es wird uns mit roten Unterstrichen auf ein Problem aufmerksam gemacht z.B. wenn wir versuchen auf eine Eigenschaft zuzugreifen, die nicht existiert oder wenn wir versuchen einen Wert eines falschen Typs zu ĂŒbergeben. Dadurch können wir Fehler frĂŒhzeitig erkennen und beheben ohne erst im Nachhinein debuggen zu mĂŒssen. Egal ob du komplett neu in der Webentwicklung bist oder ein erfahrener Profi, die "Strenge" von TypeScript wird dir ein weniger frustrierendes, konsistenteres Erlebnis bieten als Vanilla JS. + +Typsicherheit macht dich schneller. Wenn du nicht ĂŒberzeugt bist, [verwendest du TypeScript eventuell falsch...](https://www.youtube.com/watch?v=RmGHnYUqQ4k) + +## Warum Next.js? + +Wir lieben React. Es hat die Entwicklung von UIs zugĂ€nglich gemacht, auf eine Art und Weise, die wir uns vorher niemals hĂ€tten vorstellen können. Es kann Entwickler jedoch auch auf einige holprige Pfade fĂŒhren. + +Next.js bietet einen leicht von Meinung geprĂ€gten, jedoch stark optimierten Ansatz, um Anwendungen mit React zu erstellen. Von Routing ĂŒber API-Definitionen bis hin zum Rendern von Bildern vertrauen wir darauf, dass Next.js Entwickler zu guten Entscheidungen fĂŒhrt. + +## Warum tRPC/Prisma/Tailwind/etc? + +Auch wenn BefĂŒrworter davon sind, Dinge so einfach wie möglich zu halten, finden wir, dass diese Teile in jeder Anwendung verwendet werden, die wir erstellen. `create-t3-app` macht es einfach fĂŒr dich die Teile hinzuzufĂŒgen, die du benötigst. + +### tRPC + +tRPC baut auf dem Versprechen von GraphQL auf, eine nahtlose Client-Entwicklung gegen einen typsicheren Server zu ermöglichen, ohne dabei viel Boilerplate zu erzeugen. Es ist ein Missbrauch von TypeScript, der ein unglaubliches Entwicklererlebnis bietet. + +### Prisma + +Prisma ist zu SQL das Gleiche was TypeScript zu JS ist. Es hat ein Entwicklererlebnis geschaffen, dass es vorher nicht gab. +Prisma garantiert eine End-to-End Typsicherheit von deiner Datenbank bis zu deiner Anwendung, indem es Typen aus einem vom benutzerdefinierten Schema generiert, dass mit [verschiedenen Datenbanken](https://www.prisma.io/docs/concepts/database-connectors) kompatibel ist. + +Prisma bietet eine ganze [Reihe von Tools](https://www.prisma.io/docs/concepts/overview/should-you-use-prisma#-you-want-a-tool-that-holistically-covers-your-database-workflows), die das tĂ€gliche Arbeiten mit deiner Datenbank einfacher machen. Besonders hervorzuheben ist der Prisma Client, der fĂŒr das Abfragen verantwortlich und SQL so einfach macht, dass du es kaum bemerkst, dass du es benutzt. Prisma Studio ist eine hilfreiche GUI fĂŒr deine Datenbank, die es dir erlaubt, deine Daten schnell zu lesen and zu manipulieren, ohne Code schreiben zu mĂŒssen. + +### Tailwind CSS + +Tailwind fĂŒhlt sich wie "Zen-Modus CSS" an. + +Tailwind ermöglicht es dir eine anschauliche Anwendung zu erstellen, indem es dir die Grundbausteine in Form von guten Standardfarben, AbstĂ€nden und anderen Primitiven zur VerfĂŒgung stellt. Im Gegensatz zu Komponentenbibliotheken wirst du nicht dabei zurĂŒck gehalten, wenn deine Anwendung auf das nĂ€chste Level bringen möchtest und etwas außergewöhnliches und einzigartiges erstellen möchtest. + +ZusĂ€tzlich sorgt die "inline" Herangehensweise von Tailwind dafĂŒr, dass du dich nicht um Klassennamen, Ordnerstruktur oder andere Probleme sorgen musst, die nicht direkt mit dem Problem zu tun haben, dass du lösen möchtest. + +### NextAuth.js + +Wenn du ein Authentifizierungssystem in deiner Next.js-Anwendung haben möchtest, ist NextAuth.js eine ausgezeichnete Lösung, um die KomplexitĂ€t zu vermeiden, es selbst zu bauen. Es kommt mit einer umfangreichen Liste von Providern, um OAuth-Authentifizierung schnell hinzuzufĂŒgen und bietet Adapter fĂŒr viele Datenbanken und ORMs.