diff --git a/www/src/config.ts b/www/src/config.ts index f5bee22251..2527bb9121 100644 --- a/www/src/config.ts +++ b/www/src/config.ts @@ -34,6 +34,7 @@ export const KNOWN_LANGUAGES = { ja: "日本語", pt: "Português", ru: "Русский", + nl: "Nederlands", no: "Norsk", pl: "Polski", uk: "Українська", @@ -354,6 +355,37 @@ export const SIDEBAR: Sidebar = { { text: "Netlify", link: "ru/deployment/netlify" }, ], }, + nl: { + "Create T3 App": [ + { text: "Introduction", link: "nl/introduction" }, + { text: "Waarom CT3A?", link: "nl/why" }, + { text: "Installatie", link: "nl/installation" }, + { text: "Mappen-structuur", link: "nl/folder-structure" }, + { text: "FAQ", link: "nl/faq" }, + { text: "T3 Collectie", link: "nl/t3-collection" }, + { text: "Voorbeelden", link: "nl/examples" }, + { text: "Andere Aanbevelingen", link: "nl/other-recs" }, + ], + Usage: [ + { text: "Eerste Stappen", link: "nl/usage/first-steps" }, + { text: "Next.js", link: "nl/usage/next-js" }, + { text: "TypeScript", link: "nl/usage/typescript" }, + { text: "tRPC", link: "nl/usage/trpc" }, + { text: "Drizzle", link: "nl/usage/drizzle" }, + { text: "Prisma", link: "nl/usage/prisma" }, + { text: "NextAuth.js", link: "nl/usage/next-auth" }, + { + text: "Omgevingsvariabelen", + link: "nl/usage/env-variables", + }, + { text: "Tailwind CSS", link: "nl/usage/tailwind" }, + ], + Deployment: [ + { text: "Vercel", link: "nl/deployment/vercel" }, + { text: "Netlify", link: "nl/deployment/netlify" }, + { text: "Docker", link: "nl/deployment/docker" }, + ], + }, no: { "Create T3 App": [ { text: "Introduksjon", link: "no/introduction" }, @@ -464,6 +496,11 @@ export const SIDEBAR_HEADER_MAP: Record< Usage: "Использование", Deployment: "Развертывание", }, + nl: { + "Create T3 App": "Create T3 App", + Usage: "Gebruiken", + Deployment: "Uitrollen", + }, no: { "Create T3 App": "Create T3 App", Usage: "Bruk", diff --git a/www/src/pages/nl/deployment/docker.md b/www/src/pages/nl/deployment/docker.md new file mode 100644 index 0000000000..58e59ac018 --- /dev/null +++ b/www/src/pages/nl/deployment/docker.md @@ -0,0 +1,208 @@ +--- +title: Docker +description: Uitrollen met Docker +layout: ../../../layouts/docs.astro +lang: nl +--- + +Je kan deze stack containeriseren en uitrollen als één enkele container door middel van Docker. Het is ook mogelijk om de stack uit te rollen als gedeelte van een grotere groep containers door middel van docker-compose. Zie [`ajcwebdev/ct3a-docker`](https://github.com/ajcwebdev/ct3a-docker) voor een voorbeeld-repository gebasseerd op deze documentatie. + +## Docker Projectconfiguratie + +Merk op dat Next.js een ander proces gebruikt voor variablen beschikbaar in de build- (beschikbaar in de frontent, voorafgaand door `NEXT_PUBLIC`) en runtime-omgeving (enkel server-side). In deze demo maken we gebruik van twee variablen, let op hun posities in het `Dockerfile`, in de commandoregelargumenten en in het `docker-compose.yml` bestand: +- `DATABASE_URL` (wordt gebruikt door de server) +- `NEXT_PUBLIC_CLIENTVAR` (wordt gebruikt door de client) + +### 1. Next-configuratie + +Voeg in je [`next.config.js`](https://github.com/t3-oss/create-t3-app/blob/main/cli/template/base/next.config.js) de `standalone` output optie toe om [de afbeeldingsgrootte te verkleinen door automatisch gebruik te maken van output traces](https://nextjs.org/docs/advanced-features/output-file-tracing): + +```diff +export default defineNextConfig({ + reactStrictMode: true, + swcMinify: true, ++ output: "standalone", +}); +``` + +### 2. Maak het dockerignore-bestand + +
+ + Klik hier en plaats de inhoud in .dockerignore: + +
+ +``` +.env +Dockerfile +.dockerignore +node_modules +npm-debug.log +README.md +.next +.git +``` + +
+ +
+ +### 3. Maak het Dockerfile + +> Omdat we de serveromgevingsvariabelen niet in onze container trekken, zal [de validatie van het omgevingsschema](/nl/usage/env-variables) mislukken. Om dit te voorkomen moeten we een `SKIP_ENV_VALIDATION=1` flag aan het bouwcommando toevoegen zodat de env-schema's niet gevalideerd worden tijdens het bouwen. + +
+ + Klik hier en plaats de inhoud in Dockerfile: + +
+ +```docker +##### DEPENDENCIES + +FROM --platform=linux/amd64 node:20-alpine AS deps +RUN apk add --no-cache libc6-compat openssl +WORKDIR /app + +# Installeer Prisma Client - verwijder als je Prisma niet gebruikt + +COPY prisma ./ + +# Installeer dependencies met de gewenste package manager + +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:20-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 gcr.io/distroless/nodejs20-debian12 AS runner +WORKDIR /app + +ENV NODE_ENV production + +# ENV NEXT_TELEMETRY_DISABLED 1 + +COPY --from=builder /app/next.config.js ./ +COPY --from=builder /app/public ./public +COPY --from=builder /app/package.json ./package.json + +COPY --from=builder /app/.next/standalone ./ +COPY --from=builder /app/.next/static ./.next/static + +EXPOSE 3000 +ENV PORT 3000 + +CMD ["server.js"] +``` + +> **_Opmerkingen_** +> +> - _Emulatie van `--platform=linux/amd64` is mogelijk niet nodig na het overzetten naar Node 18._ +> - _Zie [`node:alpine`](https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine) om te begrijpen waarom `libc6-compat` mogelijk nodig is._ +> - _Images gebruiken die gebasseerd zijn op Alpine 3.17 [kan problemen met Prisma opleveren](https://github.com/t3-oss/create-t3-app/issues/975). `engineType = "binary"` lost het probleem in Alpine 3.17 op, [maar heeft de bijbehorende prestatieproblemen](https://www.prisma.io/docs/concepts/components/prisma-engines/query-engine#the-query-engine-at-runtime)._ +> - _Next.js verzamelt [anonieme telemetriegegevens over algemeen gebruik](https://nextjs.org/telemetry). Laat de `#` voor het eerste commentaar van `ENV NEXT_TELEMETRY_DISABLED 1` weg om telemetrie uit te schakelen tijdens de build. Doe hetzelfde met het tweede commentaar om telemetrie uit te schakelen tijdens runtime._ + +
+
+ +## Lokaal bouwen en uitvoeren + +Bouw en voer deze image lokaal uit met de volgende commando's: + +```bash +docker build -t ct3a-docker --build-arg NEXT_PUBLIC_CLIENTVAR=clientvar . +docker run -p 3000:3000 -e DATABASE_URL="database_url_goes_here" ct3a-docker +``` + +Open [localhost:3000](http://localhost:3000/) om de actieve applicatie te zien. + +## Docker Compose + +Je kan ook Docker Compose gebruiken om je image te bouwen en uit te voeren. + +
+ + Volg de stappen 1-3 van hierboven, klik hier en plaats de inhoud in docker-compose.yml: + +
+ +```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=database_url_goes_here +``` + +Bouw en begin met uitvoeren door het `docker compose up --build` commando: + +```bash +docker compose up --build +``` + +Open [localhost:3000](http://localhost:3000/) om de actieve applicatie te zien. + +
+
+ +## Uitrollen naar Railway + +Je kan een PaaS zoals [Railways](https://railway.app) geautomatiseerde [Dockerfile implementatie](https://docs.railway.app/deploy/dockerfiles) om je applicatie uit te rollen. Als je de [Railway CLI hebt geïnstallerd](https://docs.railway.app/develop/cli#install) kun je de applicatie uitrollen met de volgende commando's: + +```bash +railway login +railway init +railway link +railway up +railway open +``` + +Ga naar "Variables" en neem je `DATABASE_URL`-variable op. Ga vervolgens naar "Settings" en selecteer "Generate Domain". Om een lopend voorbeeld te bekijken op Railway bezoek je [ct3a-docker.up.railway.app](https://ct3a-docker.up.railway.app/). + +## Handige Hulpbronnen + +| Hulpbron | Link | +|----------------------------------------| -------------------------------------------------------------------- | +| Dockerfile-referentie | https://docs.docker.com/engine/reference/builder/ | +| Compose file versie 3-referentie | https://docs.docker.com/compose/compose-file/compose-file-v3/ | +| Docker CLI-referentie | https://docs.docker.com/engine/reference/commandline/docker/ | +| Docker Compose CLI-referentie | https://docs.docker.com/compose/reference/ | +| Next.js Uitrollen met Docker Image | https://nextjs.org/docs/deployment#docker-image | +| Next.js in Docker | https://benmarte.com/blog/nextjs-in-docker/ | +| Next.js met Docker Example | https://github.com/vercel/next.js/tree/canary/examples/with-docker | +| Docker Image van een Next.js-app maken | https://blog.tericcabrel.com/create-docker-image-nextjs-application/ | diff --git a/www/src/pages/nl/deployment/index.astro b/www/src/pages/nl/deployment/index.astro new file mode 100644 index 0000000000..a7a360a28e --- /dev/null +++ b/www/src/pages/nl/deployment/index.astro @@ -0,0 +1,25 @@ +--- +import IndexPage from "../../../components/docs/indexPage.astro"; +import { SIDEBAR, type Frontmatter } from "../../../config"; +import { getLanguageFromURL } from "../../../languages"; +import Layout from "../../../layouts/docs.astro"; + +const frontmatter: Frontmatter = { + title: "Uitrollen", + layout: "docs", + description: "Learn hoe je je T3-app kan uitrollen naar productie.", + lang: "nl" +}; + +const lang = getLanguageFromURL(Astro.url.pathname); +const sidebarEntries = SIDEBAR[lang]["Deployment"]!; +const files = await Astro.glob("./*.{md,mdx,astro}"); +--- + + + + diff --git a/www/src/pages/nl/deployment/netlify.mdx b/www/src/pages/nl/deployment/netlify.mdx new file mode 100644 index 0000000000..a7440b1ad3 --- /dev/null +++ b/www/src/pages/nl/deployment/netlify.mdx @@ -0,0 +1,92 @@ +--- +title: Netlify +description: Uitrollen met Netlify +layout: ../../../layouts/docs.astro +lang: nl +isMdx: true +--- + +import Callout from "../../../components/docs/callout.tsx"; + +Netlify is een alternatieve uitrolprovider vergelijkbaar met Vercel. Zie [`ajcwebdev/ct3a-netlify`](https://github.com/ajcwebdev/ct3a-netlify) voor een voorbeeld-repository gebaseerd op deze documentatie. + +## Waarom Bij Netlify Hosten + +Men verondersteld dat Vercel betere Next.js-ondersteuning heeft omdat Vercel Next.js ontwikkeld. Ze hebben er belang bij om er voor te zorgen dat het platform is afgesteld voor ideale prestaties en een ideale DX met Next.js. In de meeste gevallen zal dit ook waar zijn en is het onlogisch om af te wijken van het standaardpad. + +Maar er is ook een algemeen gevoel dat Next.js-functionaliteiten enkel ondersteund worden door Vercel. Hoewel het waar is dat nieuwe Next.js-functionaliteiten standaard getest en ondersteund worden door Vercel zodra ze uitkomen, is het ook het geval dat andere providers zoals Netlify [snel ondersteuning implementeren en vrij geven](https://www.netlify.com/blog/deploy-nextjs-13/) voor [stabiele Next.js functionaliteiten](https://docs.netlify.com/integrations/frameworks/next-js/overview/). + + +Er zijn relatieve voors en tegens voor alle uitrolproviders gezien geen enkele host de beste ondersteuning kan hebben voor alle situaties. Netlify heeft bijvoorbeeld zijn eigen [op maat gemaakte Next.js runtime](https://github.com/netlify/next-runtime) voor Netlify's Edge Functions (die draaien op Deno Deploy) en [onderhoudt unieke middleware om HTTP-responses te openen en te wijzigen](https://github.com/netlify/next-runtime#nextjs-middleware-on-netlify). + + + Zie [Using the Next 13 `app` directory on Netlify](https://github.com/netlify/next-runtime/discussions/1724) om de status bij te houden van instabiele Next 13-functionaliteiten. + + +## Projectconfiguratie + +Er zijn talrijke manieren om je buildinstructies te configureren waaronder direct via de Netlify CLI of het Netlify dashboard. Hoewel niet vereist, is het wijs om een [`netlify.toml`](https://docs.netlify.com/configure-builds/file-based-configuration/)-bestand te maken en bij te voegen. Dit zorgt ervoor dat geforkte en gekloonde versies van het project makkelijker zijn om reproduceerbaar uit te rollen. + +```toml +[build] + command = "next build" + publish = ".next" +``` + +## Het Netlify Dashboard Gebruiken + +1. Push je code naar een GitHub-repository en meld je aan bij [Netlify](https://app.netlify.com/signup). Klik nadat je een account hebt gemaakt op **Add new site** en vervolgens **Import an existing project**. + +![Nieuw project bij Netlify](/images/netlify-01-new-project.webp) + +2. Koppel je Git-provider. + +![Repository importeren](/images/netlify-02-connect-to-git-provider.webp) + +3. Selecteer de repository van je project. + +![Selecteer de repository van je project](/images/netlify-03-pick-a-repository-from-github.webp) + +4. Netlify zal kijken of je een `netlify.toml`-bestand hebt en automatisch het buildcommando en de publish-folder configureren. + +![Nextjs build-instellingen](/images/netlify-04-configure-build-settings.webp) + +5. Klik op **Show advanced** en vervolgens op **New variable** om je omgevingsvariablen toe te voegen. + +![Omgevingsvariablen toevoegen](/images/netlify-05-env-vars.webp) + +6. Klik op **Deploy site**, wacht totdat de build klaar is en bekijk je nieuwe site. + +## De Netlify CLI Gebruiken + +Om vanaf de commandline uit te rollen moet je eerst je project naar een GitHub repo pushen en [de Netlify CLI installeren](https://docs.netlify.com/cli/get-started/). Je kan `netlify-cli` als een projectdependency installeren of het globaal op je machine installeren met het volgende commando: + +```bash +npm i -g netlify-cli +``` + +Om je project lokaal te testen, voer je het [`ntl dev`](https://docs.netlify.com/cli/get-started/#run-a-local-development-environment)-commando uit en open [`localhost:88888`](http://localhost:8888/) om je lokaal draaiende Netlify-app te bekijken: + +```bash +ntl dev +``` + +Voer het [`ntl init`](https://docs.netlify.com/cli/get-started/#continuous-deployment)-commando uit om je project te configureren: + +```bash +ntl init +``` + +Importeer de omgevingsvariablen van je project vanuit het `.env`-bestand met [`ntl env:import`](https://cli.netlify.com/commands/env#envimport): + +```bash +ntl env:import .env +``` + +Rol je project uit met [`ntl deploy`](https://docs.netlify.com/cli/get-started/#manual-deploys). Je zal de `--build` flag mee moet geven aan het commando om voor uitrollen het buildcommando te draaien. Gebruik de `--prod` flag om je site uit te rollen naar de hoofd-URL: + +```bash +ntl deploy --prod --build +``` + +Bezoek [ct3a.netlify.app](https://ct3a.netlify.app/) om een werkend voorbeeld te bekijken op Netlify. diff --git a/www/src/pages/nl/deployment/vercel.md b/www/src/pages/nl/deployment/vercel.md new file mode 100644 index 0000000000..6fd364c0f4 --- /dev/null +++ b/www/src/pages/nl/deployment/vercel.md @@ -0,0 +1,62 @@ +--- +title: Vercel +description: Uitrollen met Vercel +layout: ../../../layouts/docs.astro +lang: nl +--- + +We raden aan om je app uit te rollen met [Vercel](https://vercel.com/?utm_source=t3-oss&utm_campaign=oss). Het maakt het supereenvoudig om je Next.js apps uit te rollen. + +## Projectconfiguratie + +Vercel zal waarschijnlijk je buildcommando en publish-folder automatisch configureren. Je kan deze informatie echter ook samen met andere configuraties specificeren door een bestand te maken met de naam [`vercel.json`](https://vercel.com/docs/project-configuration) en de volgende commando's in te voegen. **Dit is niet verplicht voor de meeste projecten.** + +```json +{ + "buildCommand": "npm run build", + "devCommand": "npm run dev", + "installCommand": "npm install" +} +``` + +## Het Vercel Dashboard Gebruiken + +1. Meld je aan bij [Vercel](https://vercel.com/?utm_source=t3-oss&utm_campaign=oss) met GitHub na het pushen van je code naar een GitHub-repository. Klik vervolgens op **Add new Project**. + +![Nieuw project bij Vercel](/images/vercel-new-project.webp) + +2. Importeer de GitHub-repository met je project. + +![Repository importeren](/images/vercel-import-project.webp) + +3. Voeg je omgevingsvariabelen toe. + +![Omgevingsvariablen toevoegen](/images/vercel-env-vars.webp) + +4. Klik **Deploy**. Vanaf nu zal telkens wanneer je een wijziging naar je repository pusht zal Vercel je app automatisch opnieuw uitrollen! + +## De Vercel CLI Gebruiken + +Om vanaf de commandline uit te rollen moet je eerst [de Vercel CLI globaal installeren](https://vercel.com/docs/cli#installing-vercel-cli). + +```bash +npm i -g vercel +``` + +Voer het [`vercel`](https://vercel.com/docs/cli/deploying-from-cli)-commando uit om je project uit te rollen. + +```bash +vercel +``` + +Voeg `--env DATABASE_URL=YOUR_DATABASE_URL_HERE` toe voor omgevingsvariablen zoals de databaseconnectiestring. Gebruik `--yes` als je de uitrolvragen wilt overslaan en het standaardantwoord voor elke vraag wilt geven. + +```bash +vercel --env DATABASE_URL=YOUR_DATABASE_URL_HERE --yes +``` + +Na de eerste uitrol zal dit commando naar een previewbranch uitrollen. Je zal `--prod` moeten toevoegen om je wijzigingen direct naar de live site te pushen voor komende uitrolacties. + +```bash +vercel --prod +``` diff --git a/www/src/pages/nl/examples.mdx b/www/src/pages/nl/examples.mdx new file mode 100644 index 0000000000..bc7e45fb62 --- /dev/null +++ b/www/src/pages/nl/examples.mdx @@ -0,0 +1,22 @@ +--- +title: Examples +description: Examples of different live apps +layout: ../../layouts/docs.astro +lang: en +isMdx: true +--- + +import Callout from "../../components/docs/callout.tsx"; +import Form from "../../components/docs/exampleOptionForm.astro"; + +You can try out different combinations of technologies that create-t3-app offers. + + + You cannot select `prisma` and `drizzle` at the same time. + + +
+ + + Some features might not work unless you create an env file + diff --git a/www/src/pages/nl/faq.mdx b/www/src/pages/nl/faq.mdx new file mode 100644 index 0000000000..1271158411 --- /dev/null +++ b/www/src/pages/nl/faq.mdx @@ -0,0 +1,76 @@ +--- +title: FAQ +description: Frequently asked questions about Create T3 App +layout: ../../layouts/docs.astro +lang: en +isMdx: true +--- + +import Callout from "../../components/docs/callout.tsx"; + +Here are some commonly asked questions about Create T3 App. + +## What's next? How do I make an app with this? + +We try to keep this project as simple as possible, so you can start with just the scaffolding we set up for you, and add additional things later when they become necessary. + +If you are not familiar with the different technologies used in this project, please refer to the respective docs. If you still are in the wind, please join our [Discord](https://t3.gg/discord) and ask for help. + +- [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) +- [Drizzle](https://orm.drizzle.team/docs/overview) + +## How do I keep my app up to date? + +Create T3 App is a scaffolding tool, not a framework. This means that once you initialize an app, it's yours. There is no postinstall CLI tool similar to help you stay up to date. If you want to keep track of any improvements we make to the template, you could [enable notifications for releases](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) on our repository. That being said it is not really necessary to implement every change we make to the template in your app. + +## What learning resources are currently available? + +Although the resources listed below are some of the best that exist for the T3 Stack, the community (and [Theo](https://youtu.be/rzwaaWH0ksk?t=1436)) recommend that you just start using the stack and learn along the way by building with it. + +If you are considering Create T3 App, chances are you might have already used some of the parts of the stack. So why not just dive in head first and learn the other parts while you build something? + +Now, we realize this path doesn't work for everyone. So, if you feel like you've tried the recommendation and would still like some resources, or you just aren't confident doing it by yourself and/or feel overwhelmed by the stack, checkout these awesome tutorials on Create T3 App: + +### Articles + +Some of these might be outdated. + +- [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) +- [Integrating Stripe into your T3 App](https://blog.nickramkissoon.com/posts/integrate-stripe-t3) + +### Videos + +- [T3 Stack Tutorial - FROM 0 TO PROD FOR $0 (Next.js, tRPC, TypeScript, Tailwind, Prisma & More)](https://www.youtube.com/watch?v=YkOSUVzOAA4) **(recommended)** +- [Jack Herrington - Build a Note Taking app with the T3 Stack](https://www.youtube.com/watch?v=J1gzN1SAhyM) +- [Build a Twitter Clone with the T3 Stack - tRPC, Next.js, Prisma, Tailwind & Zod](https://www.youtube.com/watch?v=nzJsYJPCc80) +- [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) + +## Why are there `.js` files in the project? + +As per [T3-Axiom #3](/en/introduction#typesafety-isnt-optional), we treat typesafety as a first class citizen. Unfortunately, not all frameworks and plugins support TypeScript which means some of the configuration files have to be `.js` files. + +We try to emphasize that these files are JavaScript for a reason, by explicitly declaring each file's type (`cjs` or `mjs`) depending on what's supported by the library it is used by. Also, all the `js` files in this project are still typechecked using a checkJs option in the compiler (tsconfig). + +## I'm struggling to add i18n to my app. Is there any reference I can use? + +We have decided against including i18n by default in `create-t3-app` because it's a very opinionated topic and there are many ways to implement it. + +However, if you struggle to implement it and want to see a reference project, we have a [reference repo](https://github.com/juliusmarminge/t3-i18n) that shows how you can add i18n to a T3 App using [next-i18next](https://github.com/i18next/next-i18next). + +## Why are we using `/pages` and not `/app` from Next.js 13? + +As per [T3-Axiom #2](/en/introduction#bleed-responsibly), we love bleeding edge stuff but value stability, your entire router is hard to port, [not a great place to bleed](https://youtu.be/mnwUbtieOuI?t=1662). While `/app` is [a glimpse into the future](https://youtu.be/rnsC-12PVlM?t=818), it's not ready for production; The API is in beta and expected to have breaking changes. + + + For a list of supported, planned, and worked on features in the `/app` dir, + visit the [beta Next.js + docs](https://beta.nextjs.org/docs/app-directory-roadmap#supported-and-planned-features). + diff --git a/www/src/pages/nl/folder-structure.mdx b/www/src/pages/nl/folder-structure.mdx new file mode 100644 index 0000000000..446e910953 --- /dev/null +++ b/www/src/pages/nl/folder-structure.mdx @@ -0,0 +1,212 @@ +--- +title: Folder Structure +description: Folder structure of a newly scaffolded T3 App +layout: ../../layouts/docs.astro +lang: en +isMdx: true +--- + +import Diagram from "../../components/docs/folderStructureDiagram.astro"; +import Form from "../../components/docs/folderStructureForm.astro"; + +Please select your packages to see the folder structure of a newly scaffolded app with those selections. Further down, you will find a description of each entry. + + + + + +
+ +### `prisma` + +The `prisma` folder contains the `schema.prisma` file which is used to configure the database connection and the database schema. It is also the location to store migration files and/or seed scripts, if used. See [Prisma usage](/en/usage/prisma) for more information. + +
+
+ +### `public` + +The `public` folder contains static assets that are served by the web server. The `favicon.ico` file is an example of a static asset. + +
+
+ +### `src/env` + +Used for environment variable validation and type definitions - see [Environment Variables](usage/env-variables). + +
+
+ +### `src/pages` + +The `pages` folder contains all the pages of the Next.js application. The `index.tsx` file at the root directory of `/pages` is the homepage of the application. The `_app.tsx` file is used to wrap the application with providers. See [Next.js documentation](https://nextjs.org/docs/basic-features/pages) for more information. + +
+
+ +#### `src/pages/api` + +The `api` folder contains all the API routes of the Next.js application. See [Next.js Api Routes Docs](https://nextjs.org/docs/api-routes/introduction) for info on api routes. + +
+
+ +#### `src/pages/api/auth/[...nextauth].ts` + +The `[...nextauth].ts` file is the NextAuth.js authentication slug route. It is used to handle authentication requests. See [NextAuth.js usage](usage/next-auth) for more information on NextAuth.js, and [Next.js Dynamic Routes Docs](https://nextjs.org/docs/routing/dynamic-routes) for info on catch-all/slug routes. + +
+
+ +#### `src/pages/api/trpc/[trpc].ts` + +The `[trpc].ts` file is the tRPC API entrypoint. It is used to handle tRPC requests. See [tRPC usage](usage/trpc#-pagesapitrpctrpcts) for more information on this file, and [Next.js Dynamic Routes Docs](https://nextjs.org/docs/routing/dynamic-routes) for info on catch-all/slug routes. + +
+
+ +### `src/server` + +The `server` folder is used to clearly separate server-side code from client-side code. + +
+
+ +#### `src/server/auth.ts` + +The main entrypoint for server-side authentication logic. Here, we setup the NextAuth.js [configuration options](usage/next-auth), perform [module augmentation](usage/next-auth#inclusion-of-userid-on-the-session) as well as provide some DX utilities for authentication such as retrieving the user's session on the server-side. See [NextAuth.js usage](usage/next-auth#usage-with-trpc) for more information. + +
+
+ +#### `src/server/db.ts` + +The `db.ts` file is used to instantiate the Prisma client at global scope. See [Prisma usage](usage/prisma#prisma-client) and [best practices for using Prisma with Next.js](https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices) for more information. + +
+
+ +### `src/server/api` + +The `api` folder contains the tRPC server-side code. + +
+
+ +#### `src/server/api/routers` + +The `routers` folder contains all your tRPC sub-routers. + +
+
+ +#### `src/server/api/routers/example.ts` + +The `example.ts` file is an example tRPC router utilizing the `publicProcedure` helper to demonstrate how to create a public tRPC route. + +Depending on your chosen packages this router contains more or less routes to best demonstrate the usage to your needs. + +
+
+ +#### `src/server/api/trpc.ts` + +The `trpc.ts` file is the main configuration file for your tRPC back-end. In here we: + +1. Define context used in tRPC requests. See [tRPC usage](usage/trpc#-serverapitrpcts) for more information. +2. Export procedure helpers. See [tRPC usage](usage/trpc#-serverapitrpcts) for more information. + +
+ +
+ +#### `src/server/api/root.ts` + +The `root.ts` file is used to merge tRPC routers and export them as a single router, as well as the router's type definition. See [tRPC usage](usage/trpc#-serverapirootts) for more information. + +
+
+ +### `src/styles` + +The `styles` folder contains the global styles of the application. + +
+
+ +### `src/utils` + +The `utils` folder is used to store commonly re-used utility functions. + +
+
+ +#### `src/utils/api.ts` + +The `api.ts` file is the front-end entrypoint to tRPC. See [tRPC usage](usage/trpc#-utilsapits) for more information. + +
+
+ +### `.env` + +The `.env` file is used to store environment variables. See [Environment Variables](usage/env-variables) for more information. This file should **not** be committed to git history. + +
+
+ +### `.env.example` + +The `.env.example` file shows example environment variables based on the chosen libraries. This file should be committed to git history. + +
+
+ +### `.eslintrc.cjs` + +The `.eslintrc.cjs` file is used to configure ESLint. See [ESLint Docs](https://eslint.org/docs/latest/user-guide/configuring/configuration-files) for more information. + +
+
+ +### `next-env.d.ts` + +The `next-env.d.ts` file ensures Next.js types are picked up by the TypeScript compiler. **You should not remove it or edit it as it can change at any time.** See [Next.js Docs](https://nextjs.org/docs/basic-features/typescript#existing-projects) for more information. + +
+
+ +### `next.config.mjs` + +The `next.config.mjs` file is used to configure Next.js. See [Next.js Docs](https://nextjs.org/docs/api-reference/next.config.js/introduction) for more information. Note: The .mjs extension is used to allow for ESM imports. + +
+
+ +### `postcss.config.cjs` + +The `postcss.config.cjs` file is used for Tailwind PostCSS usage. See [Tailwind PostCSS Docs](https://tailwindcss.com/docs/installation/using-postcss) for more information. + +
+
+ +### `prettier.config.mjs` + +The `prettier.config.mjs` file is used to configure Prettier to include the prettier-plugin-tailwindcss for formatting Tailwind CSS classes. See the [Tailwind CSS blog post](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier) for more information. + +
+
+ +### `tsconfig.json` + +The `tsconfig.json` file is used to configure TypeScript. Some non-defaults, such as `strict mode`, have been enabled to ensure the best usage of TypeScript for Create T3 App and its libraries. See [TypeScript Docs](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) or [TypeScript Usage](usage/typescript) for more information. + +
+
+ +### `drizzle.config.ts` + +The `drizzle.config.ts` file is used to configure drizzle kit. See [the documentation](https://orm.drizzle.team/kit-docs/config-reference) for more information. + +
\ No newline at end of file diff --git a/www/src/pages/nl/installation.mdx b/www/src/pages/nl/installation.mdx new file mode 100644 index 0000000000..caf4aca1e3 --- /dev/null +++ b/www/src/pages/nl/installation.mdx @@ -0,0 +1,72 @@ +--- +title: Installation +description: Installation instructions for Create T3 App +layout: ../../layouts/docs.astro +lang: en +isMdx: true +--- + +import Callout from "../../components/docs/callout.tsx"; + +To scaffold an app using `create-t3-app`, run any of the following commands and answer the command prompt questions: + +### npm + +```bash +npm create t3-app@latest +``` + +### yarn + +```bash +yarn create t3-app +``` + +### pnpm + +```bash +pnpm create t3-app@latest +``` + +### bun + +```bash +bun create t3-app@latest +``` + +After your app has been scaffolded, check out the [first steps](/en/usage/first-steps) to get started on your new application. + +## Advanced usage + +| Option/Flag | Description | +| ----------------- | ----------------------------------------------------------------------- | +| `[dir]` | Include a directory argument with a name for the project | +| `--noGit` | Explicitly tell the CLI to not initialize a new git repo in the project | +| `-y`, `--default` | Bypass the CLI and bootstrap a new t3-app with all options selected | +| `--noInstall` | Generate project without installing dependencies | + +## Experimental usage + +For our CI, we have some experimental flags that allow you to scaffold any app without any prompts. If this use case applies to you, you can use these flags. Please note that these flags are experimental and may change in the future without following semver versioning. + +| Flag | Description | +| ------------ | ----------------------------------- | +| `--CI` | Let the CLI know you're in CI mode | +| `--trpc` | Include tRPC in the project | +| `--prisma` | Include Prisma in the project | +| `--nextAuth` | Include NextAuth.js in the project | +| `--tailwind` | Include Tailwind CSS in the project | + + + If you don't provide the `CI` flag, the rest of these flags have no effect. + + +You don't need to explicitly opt-out of the packages you don't want. However, if you prefer to be explicit, you can pass `false`, e.g. `--nextAuth false`. + +### Example + +The following would scaffold a T3 App with tRPC and Tailwind CSS. + +```bash +pnpm dlx create-t3-app@latest --CI --trpc --tailwind +``` diff --git a/www/src/pages/nl/introduction.md b/www/src/pages/nl/introduction.md new file mode 100644 index 0000000000..f973ded24f --- /dev/null +++ b/www/src/pages/nl/introduction.md @@ -0,0 +1,42 @@ +--- +title: Introduction +description: Introduction to the T3 Stack +layout: ../../layouts/docs.astro +lang: en +--- + +
+ +
+ +## The T3 Stack + +The _"T3 Stack"_ is a web development stack made by [Theo](https://twitter.com/t3dotgg) focused on simplicity, modularity, and full-stack typesafety. + +The core pieces are [**Next.js**](https://nextjs.org/) and [**TypeScript**](https://typescriptlang.org/). [**Tailwind CSS**](https://tailwindcss.com/) is almost always included. If you're doing anything resembling backend, [**tRPC**](https://trpc.io/), [**Prisma**](https://prisma.io/), and [**NextAuth.js**](https://next-auth.js.org/) are great additions too. + +You may have noticed that there are a… lot of pieces. That's by design. Swap pieces in and out as you need - this stack is modular at its core :) + +## So... what is create-t3-app? A template? + +Kind of? `create-t3-app` is a CLI built by seasoned T3 Stack devs to streamline the setup of a modular T3 Stack app. This means each piece is optional, and the "template" is generated based on your specific needs. + +After countless projects and many years on this tech, we have lots of opinions and insights. We've done our best to encode them into this CLI. + +This is **NOT** an all-inclusive template. We **expect** you to bring your own libraries that solve the needs of **YOUR** application. While we don't want to prescribe solutions to more specific problems like state management and deployment, we [do have some recommendations listed here](/en/other-recs). + +## T3 Axioms + +We'll be frank - this is an _opinionated project_. We share a handful of core beliefs around building and we treat them as the basis for our decisions. + +### Solve Problems + +It's easy to fall into the trap of "adding everything" - we explicitly don't want to do that. Everything added to `create-t3-app` should solve a specific problem that exists within the core technologies included. This means we won't add things like state libraries (`zustand`, `redux`) but we will add things like NextAuth.js and integrate Prisma and tRPC for you. + +### Bleed Responsibly + +We love our bleeding edge tech. The amount of speed and, honestly, fun that comes out of new shit is really cool. We think it's important to bleed responsibly, using riskier tech in the less risky parts. This means we wouldn't ⛔️ bet on risky new database tech (SQL is great!). But we happily ✅ bet on tRPC since it's just functions that are trivial to move off. + +### Typesafety Isn't Optional + +The stated goal of Create T3 App is to provide the quickest way to start a new full-stack, **typesafe** web application. We take typesafety seriously in these parts as it improves our productivity and helps us ship fewer bugs. Any decision that compromises the typesafe nature of Create T3 App is a decision that should be made in a different project. diff --git a/www/src/pages/nl/other-recs.md b/www/src/pages/nl/other-recs.md new file mode 100644 index 0000000000..d3319ccaae --- /dev/null +++ b/www/src/pages/nl/other-recs.md @@ -0,0 +1,163 @@ +--- +title: Other Recommendations +description: Libraries and Services that we recommend for many projects +layout: ../../layouts/docs.astro +lang: en +--- + +We recognize that the libraries included in `create-t3-app` don't solve every problem. While we encourage you to begin your project with the things that we provide, there will come a time when you need to bring in other packages. Only you can know what your project needs, but here are some things that we find ourselves recommending frequently. + +These are recommendations by individual Create T3 App contributors and should not be seen as "official" endorsements by the Create T3 App team or T3-OSS. _**Please do your own research, especially before committing to paid services**_. + +## State Management + +_**Editor's Note**_: State management libraries can be great, but often aren't necessary. tRPC's React Query hooks should be able to take care of your server state. For client state, start with React's `useState`, and reach for one of these options when you need more. + +### Zustand + +**For never using Redux again** + +The "modern, simple Redux" you didn't know you needed. [Poimandres](https://github.com/pmndrs) can always be trusted. You can build everything from video call apps to games to servers with this little library. + +- [Zustand Homepage](https://zustand-demo.pmnd.rs/) +- [Zustand GitHub](https://github.com/pmndrs/zustand) + +### Jotai + +**For never using Context again** + +For a more atomic approach, Jotai is hard to beat. Also by [Poimandres](https://github.com/pmndrs), Jotai lets you define singletons that feel like global useState. A great option for stateful behaviors that don't need a state machine just yet. + +- [Jotai Homepage](https://jotai.org/) +- [Jotai GitHub](https://github.com/pmndrs/jotai) + +## Component Libraries + +Most apps need the same handful of components - toggle buttons, dropdown menus, modals, and so on. These libraries provide great, accessible components that you can use and customize to your liking. + +### Unstyled Component Libraries + +Also known as headless libraries, they provide great unstyled, and accessible components that you can customize to your liking. Here are a few recommendations. + +- [Radix UI](https://www.radix-ui.com/) gives you a powerful set of convenient and accessible primitives that you can style with vanilla or Tailwind CSS. + +- [Headless UI](https://headlessui.com/) made by the Tailwind CSS team also provides unstyled, accessible components that integrate seamlessly with Tailwind CSS. + +- [React Aria](https://react-spectrum.adobe.com/react-aria/) provides accessible UI primitives for your design system. Their Date Picker component is top tier. + +### Styled Component Libraries + +**For when you just want your app to look OK** + +Sometimes you're building a project where you just want the UI to look decent out of the box. For Admin Dashboards and other similar projects, any of these component libraries will get the job done. + +- [Chakra UI](https://chakra-ui.com) +- [Mantine](https://mantine.dev) +- [@shadcn/ui](https://ui.shadcn.com/) + +### Class Variance Authority + +**For building UI Libraries** + +Declaratively build a UI Library with different color, size, etc. variants. When your project reaches a scale where you want a standardized set of UI components with multiple variants using Tailwind CSS, CVA is a great tool. + +- [Class Variance Authority GitHub](https://github.com/joe-bell/cva) + +## Animations + +For when you need animations in your app, here are our recommendations. + +### AutoAnimate + +**For animations with a single line of code** + +Most animation libraries try to satisfy every possible use case, and become clunky as a result. AutoAnimate is a zero-configuration tool that will give you a significant improvement in UX with no additional developer effort. + +- [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 + +**For complex animations with declarative code** + +Framer Motion provides a simple, declarative syntax and allows you to write less code to craft everything from complex animations to even gestures. + +- [Framer Motion Homepage](https://framer.com/motion) +- [Framer Motion Documentation](https://www.framer.com/docs/) + +## Deployments, Infrastructure, Databases and CI + +### Vercel + +**For hosting your app** + +Vercel took the hell of web deployments and made it a set-and-forget GitHub integration. We've scaled to hundreds of thousands of users without issue. AWS-powered, just a way better interface :) + +- [Vercel Homepage](https://vercel.com/) +- [Create T3 App Vercel deployment guide](/en/deployment/vercel) + +### PlanetScale + +**For databases without the worry** + +PlanetScale is the best "serverless database platform" we've used by far. Insane scale, great developer experience, and fantastic pricing. If you're using SQL (and hopefully Prisma), this is hard to beat. + +- [PlanetScale Homepage](https://planetscale.com/) + +### Railway + +**For hosting your infra** + +"Modern Heroku". The easiest way to get a real server up and running. If Vercel and PlanetScale aren't enough, Railway probably is. Point it at a GitHub repo and go. + +- [Railway Homepage](https://railway.app/) + +### Upstash + +**For serverless Redis** + +We love Prisma and PlanetScale, but some projects require a more performant solution. Upstash allows you to get the in-memory performance of Redis in your serverless project, without having to manage the infrastructure and scaling yourself. + +- [Upstash Homepage](https://upstash.com/) + +### Pusher + +**For serverless WebSockets** + +If WebSockets are the primary focus of your project, you may want to consider a more traditional backend such as [Fastify](https://www.fastify.io/) (which [also works with tRPC!](https://trpc.io/docs/v10/fastify)). But for quickly adding WebSockets to a T3 App, Pusher is an excellent choice. + +- [Pusher Homepage](https://pusher.com/) + +### Soketi + +Soketi is a self-hostable, simple, and fast alternative to Pusher. It's fully compatible with the Pusher SDK which you can use to connect to the server. Soketi serverless is also in beta. + +- [Soketi Homepage](https://soketi.app) +- [Soketi GitHub](https://github.com/soketi/soketi) + +## Analytics + +User data is very valuable when you're building an app. Here are some analytics providers we recommend. + +### Plausible + +Need analytics? Plausible is one of the quickest ways to get them. Super minimal. It even has a [simple plugin for Next.js](https://plausible.io/docs/proxy/guides/nextjs). + +- [Plausible Homepage](https://plausible.io/) + +### Umami + +Umami is an open-sourced, self-hostable, simple, fast, privacy-focused alternative to Google Analytics. You can deploy it really easily to Vercel, Railway, etc. with PlanetScale as your database or you can also use its cloud version. + +- [Umami Homepage](https://umami.is/) +- [Umami GitHub](https://github.com/umami-software/umami) +- [Umami Cloud](https://cloud.umami.is/) + +## Other + +### Next Bundle Analyzer + +It can sometimes be difficult to determine what will be included in the build output for your app. Next Bundle Analyzer is an easy way to visualize and analyze the JavaScript bundles that are generated. + +- [@next/bundle-analyzer on npm](https://www.npmjs.com/package/@next/bundle-analyzer) diff --git a/www/src/pages/nl/t3-collection.mdx b/www/src/pages/nl/t3-collection.mdx new file mode 100644 index 0000000000..8c8cfcb9b1 --- /dev/null +++ b/www/src/pages/nl/t3-collection.mdx @@ -0,0 +1,29 @@ +--- +title: T3 Collection +description: Cool open source projects and companies using the T3 stack +layout: ../../layouts/docs.astro +lang: en +isMdx: true +--- + +import OpenSourceAppList from "../../components/docs/openSourceAppList.tsx"; +import CompanyList from "../../components/docs/companyList.tsx"; +import Callout from "../../components/docs/callout.tsx"; + +Made a project using the T3 stack and want to share it? Add it to the list! + +## Open Source apps made using the T3 Stack + + + +## Companies using the T3 Stack + +We'd love to know of companies that use the T3 stack for their apps. Is your company using the T3 stack and would like to share it? Add it to the list! + + + + + Have a cool project using the T3 stack? Make a [pull + request](https://github.com/t3-oss/create-t3-app/tree/next/www/src/components/docs/openSourceAppList.tsx) + and add it here! + diff --git a/www/src/pages/nl/usage/drizzle.mdx b/www/src/pages/nl/usage/drizzle.mdx new file mode 100644 index 0000000000..a1274612ba --- /dev/null +++ b/www/src/pages/nl/usage/drizzle.mdx @@ -0,0 +1,14 @@ +--- +title: Drizzle +description: Gebruik van Drizzle +layout: ../../../layouts/docs.astro +lang: nl +isMdx: true +--- + +import Callout from "../../../components/docs/callout.tsx"; + + + De `drizzle`-optie is een nieuwe toevoeging en er is nog geen documentatie geschreven. Bijdragen zijn van harte welkom! + + \ No newline at end of file diff --git a/www/src/pages/nl/usage/env-variables.mdx b/www/src/pages/nl/usage/env-variables.mdx new file mode 100644 index 0000000000..dd8a22eb70 --- /dev/null +++ b/www/src/pages/nl/usage/env-variables.mdx @@ -0,0 +1,147 @@ +--- +title: Omgevingsvariabelen +description: Aan de slag met Create T3 App +layout: ../../../layouts/docs.astro +lang: nl +isMdx: true +--- + +import Callout from "../../../components/docs/callout.tsx"; + +Create T3 App maakt intern gebruik van zijn eigen package [@t3-oss/env-nextjs](https://env.t3.gg) en van [zod](https://zod.dev) om omgevingsvariabelen zowel tijdens runtime als *buildtime* te valideren door een eenvoudige logica aan te bieden in `src/env.js`. + +## env.js + +_TDLR; Als je een nieuwe omgevingsvariabele wil toevoegen, moet je er een validator voor toevoegen in `src/env.js` en dan het KV-paar toevoegen in `.env`_ + +```ts:env.js +import { createEnv } from "@t3-oss/env-nextjs"; +import { z } from "zod"; + +export const env = createEnv({ + server: { + NODE_ENV: z.enum(["development", "test", "production"]), + }, + client: { + // NEXT_PUBLIC_CLIENTVAR: z.string(), + }, + runtimeEnv: { + NODE_ENV: process.env.NODE_ENV, + }, +}); +``` + +T3 Env gebruikt de functie `createEnv` om het schema te maken en zowel client- als server-side-omgevingsvariabelen to valideren. + + + Voor meer informatie over hoe `createEnv` intern werkt, bekijk je de [T3 Env](https://env.t3.gg/docs/introduction) docs. + + +## Omgevingsvariabelen Gebruiken + +Wanneer je gebruik wilt maken van je omgevingsvariabelen, kun je ze importeren vanuit het gemaakte `env.js` en ze gebruiken zoals je dat doorgaands ook zou doen. Als je op de client gebruik probeert te maken van een server-side omgevingsvariabele, zal je een runtime error ontvangen. + +```ts:pages/api/hello.ts +import { env } from "../../env.js"; + +// `env` is volledig typesafe en biedt autocompletion +const dbUrl = env.DATABASE_URL; +``` + +```ts:pages/index.tsx +import { env } from "../env.js"; + +// ❌ Dit zal een runtime error opleveren +const dbUrl = env.DATABASE_URL; + +// ✅ Dit is prima +const wsKey = env.NEXT_PUBLIC_WS_KEY; +``` + +## .env.example + +Omdat het standaard `.env`-bestand niet wordt vastgelegd in version contol, hebben we ook een `.env.example`-bestand meegeleverd, waarin je optioneel een kopie van je `.env`-bestand kan bewaren met alle secrets verwijderd. Dit is niet verplicht, maar we raden aan om het voorbeeld regelmatig bij te werken om het zo makkelijk mogelijk te maken voor bijdragers om aan de slag te gaan met hun omgeving. + +Sommige frameworks en buildtools, zoals Next.js, stellen voor om je secrets in een `.env.local`-bestand te bewaren en `.env`-bestanden naar je project vast te leggen. Dit wordt afgeraden, omdat dit het te eenvoudig kan maken om per ongeluk secrets naar je project vast te leggen. In plaats daarvan raden wij aan dat je secrets in `.env` bewaart en je `.env`-bestand in je `.gitignore` houdt en alleen `.env.example`-bestanden naar je project vastlegt. + +## Omgevingsvariabelen Toevoegen + +Om je ervan te verzekeren dat je build nooit voltooid zonder de vereiste omgevingsvariabelen, moet je nieuwe omgevingsvariabelen in **twee** plekken vastleggen: + +📄 `.env`: Voer je omgevingsvariabele in zoals je dat normaliter ook in een `.env`-bestand zou doen, bijv. `SLEUTEL=WAARDE` + +📄 `env.js`: Voeg de gepaste validatielogica voor de omgevingsvariabelen toe door voor ze allemaal in `createEnv` een Zod-schema te definiëren, bijv. `SLEUTEL: z.string()`. Zorg er daarnaast voor dat je ze vernietigt in de runtimeEnv optie, bijv: `SLEUTEL: process.env.SLEUTEL` + + + Waarom moet ik de omgevingsvariabele in de `runtimeEnv` vernietigen? + Dit komt door de manier waarop Next.js omgevingsvariabelen bundelt in bepaalde runtimes. + Door deze handmatig te vernietigen, zorg je ervoor dat de variabele nooit uit de bundle zal worden gehaald. + + +Je kan `.env.example` up-to-date houden: + +📄 `.env.example`: Voer je omgevingsvariabele in, maar laat de waarde leeg als het een secret is, bijv. `SLEUTEL=WAARDE` of `SLEUTEL=` + +### Voorbeeld + +_Ik wil mijn Twitter API-Sleutel toevoegen als een server-side omgevingsvariabele_ + +1. Voeg de omgevingsvariabele toe aan `.env`: + +``` +TWITTER_API_SLEUTEL=1234567890 +``` + +2. Voeg de omgevingsvariabele toe aan `env.js`: + +```ts +import { createEnv } from "@t3-oss/env-nextjs"; +import { z } from "zod"; + +export const env = createEnv({ + server: { + TWITTER_API_SLEUTEL: z.string(), + }, + // ... + runtimeEnv: { + // ... + TWITTER_API_SLEUTEL: process.env.TWITTER_API_SLEUTEL, + }, +}); +``` + +3. _Optioneel:_ Voeg de omgevingsvariabele toe aan `.env.example` en laat het secret weg in de `runtimeEnv`-optie + +```bash +TWITTER_API_SLEUTEL= +``` + +## Type Coercion + +Alle variabelen die je toevoegt aan `.env` zullen geïmporteerd worden als strings, zelfs als hun waarde bedoeld is om een andere type te vertegenwoordigen. Als je je omgevingsvariabele als een andere type wil gebruiken tijdens runtime, kun je Zod's `coerce` gebruiken om de string om te zetten naar de andere type die je wil. Het zal een error opleveren als het mislukt. + +Voeg de variabelen toe aan je `.env`: + +``` +EEN_GETAL=123 +EEN_BOOLEAN=true +``` + +Valideer ze vervolgens in `env.js`: + +```ts +import { createEnv } from "@t3-oss/env-nextjs"; +import { z } from "zod"; + +export const env = createEnv({ + server: { + EEN_GETAL: z.coerce.number(), + EEN_BOOLEAN: z.coerce.boolean(), + }, + // ... + runtimeEnv: { + EEN_GETAL: process.env.EEN_GETAL, + EEN_BOOLEAN: process.env.EEN_BOOLEAN, + }, +}); +``` diff --git a/www/src/pages/nl/usage/first-steps.md b/www/src/pages/nl/usage/first-steps.md new file mode 100644 index 0000000000..f047b717ff --- /dev/null +++ b/www/src/pages/nl/usage/first-steps.md @@ -0,0 +1,54 @@ +--- +title: Eerste Stappen +description: Aan de slag met Create T3 App +layout: ../../../layouts/docs.astro +lang: nl +--- + +Je hebt zojuist een nieuwe T3 App in de steigers gezet en staat klaar voor de start. Hier is het minimale om je app werkende te krijgen. + +## Database + +### MySQL, PostgreSQL + +Als je MySQL of PostgreSQL als je database hebt gekozen, zal T3 app een `start-database.sh` bash-script meeleveren dat een docker container met een database kan maken voor lokale ontwikkling. Als je al een database hebt, voel je vrij om dit bestand te verwijderen en je databasegegevens in `.env` te plaatsen. Op macOS kun je ook [DBNgin](https://dbngin.com/) in plaats van Docker gebruiken. + +### Prisma + +Als je app Prisma bevat, voer dan `npx prism db push` vanaf de hoofdmap van je app uit. Dit commando zal je Prisma-schema met je database synchroniseren en zal de TypeScript-types voor de Prisma-Client genereren op basis van je schema. Onthoud dat je [de TypeScript-server moet herstarten](https://tinytip.co/tips/vscode-restart-ts/) nadat je dit hebt gedaan zodat deze de gegenereerde types kan ontdekken. + +### Drizzle + +Als je app Drizzle bevat, controleer dan het `.env`-bestand voor instructies over hoe je je `DATABSE_URL` omgevingsvariabele moet opbouwen. Wanneer je env-bestand klaar is, voer `pnpm db:push` (of de equivalent voor andere package managers) uit om je schema te pushen. + +## Authenticatie + +Als je app NextAuth.js bevat, laten we je aan de slag gaan met de `DiscordProvider`. Dit is een van de eenvoudigste providers die NextAuth.js biedt, maar vereist nog steeds een kleine initiële installatie door jou. + +Natuurlijk, als je liever een andere authenticatieprovider gebruikt, kun je ook een van de [vele providers](https://next-auth.js.org/providers/) gebruiken die NextAuth.js biedt. + +1. Je zal een Discord-account nodig hebben, dus maak er een aan als je dat nog niet hebt gedaan. +2. Navigeer naar https://discord.com/developers/applications en klik op "New Application" in de rechterbovenhoek. Geef je applicatie een naam en stem in met de Servicevoorwaarden. +3. Wanneer je applicatie is gemaakt, navigeer je naar "Settings → OAuth2 → General". +4. Kopieer de "Client ID" and voeg het toe aan je `.env` als `DISCORD_CLIENT_ID`. +5. Klik op "Reset Secret", kopieer het nieuwe secret en voeg het toe aan je `.env.` als `DISCORD_CLIENT_SECRET`. +6. Klik op "Add Redirect" en typ `http://localhost:3000/api/auth/callback/discord`. + - Voor een productie-uitrol volg je de voorgaande stappen om een andere Discord-applicatie te maken, maar vervang je deze keer `http://localhost:3000` met de URL waarnaar je uitrolt. +7. Bewaar de Wijzigingen. +8. Stel de `NEXTAUTH_SECRET` in `.env` in. Tijdens ontwikkeling is een willekeurige string voldoende, voor productie zie de opmerking in `.env` over het genereren van een veilig secret. + +Je zou nu moeten kunnen inloggen. + +## Editor Instellen + +De volgende extensies zijn aangeraden voor een optimale ontwikkelaarservaring. De onderstaande links bieden editor-specifieke plugin-ondersteuning. + +- [Prisma Extension](https://www.prisma.io/docs/guides/development-environment/editor-setup) +- [Tailwind CSS IntelliSense Extension](https://tailwindcss.com/docs/editor-setup) +- [Prettier Extension](https://prettier.io/docs/en/editors.html) + +## Volgende Stappen + +- Als je app tRPC bevat, bekijk `src/pages/index.tsx` en `src/server/api/routers/post.ts` om te bekijken hoe tRPC-queries werken. +- Kijk eens rond in de Create T3 App-documentatie en de documentatie van packages die je app bevat. +- Word lid van onze [Discord](https://t3.gg/discord) en geef ons een ster op [GitHub](https://github.com/t3-oss/create-t3-app)! :) \ No newline at end of file diff --git a/www/src/pages/nl/usage/index.astro b/www/src/pages/nl/usage/index.astro new file mode 100644 index 0000000000..4c31ec7bf1 --- /dev/null +++ b/www/src/pages/nl/usage/index.astro @@ -0,0 +1,24 @@ +--- +import IndexPage from "../../../components/docs/indexPage.astro"; +import { SIDEBAR, type Frontmatter } from "../../../config"; +import { getLanguageFromURL } from "../../../languages"; +import Layout from "../../../layouts/docs.astro"; + +const frontmatter: Frontmatter = { + title: "Usage", + layout: "docs", + description: "Learn how to use the different technology from the T3 Stack.", +}; + +const lang = getLanguageFromURL(Astro.url.pathname); +const sidebarEntries = SIDEBAR[lang]["Usage"]!; +const files = await Astro.glob("./*.{md,mdx,astro}"); +--- + + + + diff --git a/www/src/pages/nl/usage/next-auth.mdx b/www/src/pages/nl/usage/next-auth.mdx new file mode 100644 index 0000000000..7a5d68d5b0 --- /dev/null +++ b/www/src/pages/nl/usage/next-auth.mdx @@ -0,0 +1,228 @@ +--- +title: NextAuth.js +description: Usage of NextAuth.js +layout: ../../../layouts/docs.astro +lang: en +isMdx: true +--- + +import Callout from "../../../components/docs/callout.tsx"; + +When you want an authentication system in your Next.js application, NextAuth.js is an excellent solution to bring in the complexity of security without the hassle of having to build it yourself. It comes with an extensive list of providers to quickly add OAuth authentication and provides adapters for many databases and ORMs. + +## Context Provider + +In your app's entrypoint, you'll see that your application is wrapped in a [SessionProvider](https://next-auth.js.org/getting-started/client#sessionprovider): + +```tsx:pages/_app.tsx + + + +``` + +This context provider allows your application to access the session data from anywhere in your application, without having to pass it down as props: + +```tsx:pages/users/[id].tsx +import { useSession } from "next-auth/react"; + +const User = () => { + const { data: session } = useSession(); + + if (!session) { + // Handle unauthenticated state, e.g. render a SignIn component + return ; + } + + return

Welcome {session.user.name}!

; +}; +``` + +## Retrieving session server-side + +Sometimes you might want to request the session on the server. To do so, prefetch the session using the `getServerAuthSession` helper function that `create-t3-app` provides, and pass it down to the client using `getServerSideProps`: + +```tsx:pages/users/[id].tsx +import { getServerAuthSession } from "../server/auth"; +import { type GetServerSideProps } from "next"; + +export const getServerSideProps: GetServerSideProps = async (ctx) => { + const session = await getServerAuthSession(ctx); + return { + props: { session }, + }; +}; + +const User = () => { + const { data: session } = useSession(); + // NOTE: `session` wont have a loading state since it's already prefetched on the server + + ... +} +``` + +## Inclusion of `user.id` on the Session + +Create T3 App is configured to utilise the [session callback](https://next-auth.js.org/configuration/callbacks#session-callback) in the NextAuth.js config to include the user's ID within the `session` object. + +```ts:server/auth.ts +callbacks: { + session({ session, user }) { + if (session.user) { + session.user.id = user.id; + } + return session; + }, + }, +``` + +This is coupled with a type declaration file to make sure the `user.id` is typed when accessed on the `session` object. Read more about [`Module Augmentation`](https://next-auth.js.org/getting-started/typescript#module-augmentation) on NextAuth.js's docs. + +```ts:server/auth.ts +import { DefaultSession } from "next-auth"; + +declare module "next-auth" { + interface Session { + user?: { + id: string; + } & DefaultSession["user"]; + } +} +``` + +The same pattern can be used to add any other data to the `session` object, such as a `role` field, but **should not be misused to store sensitive data** on the client. + +## Usage with tRPC + +When using NextAuth.js with tRPC, you can create reusable, protected procedures using [middleware](https://trpc.io/docs/v10/middlewares). This allows you to create procedures that can only be accessed by authenticated users. `create-t3-app` sets all of this up for you, allowing you to easily access the session object within authenticated procedures. + +This is done in a two step process: + +1. Grab the session from the request headers using the [`getServerSession`](https://next-auth.js.org/configuration/nextjs#getServerSession) function. The advantage of using `getServerSession` instead of the regular `getSession` is that it's a server-side only function and doesn't trigger unnecessary fetch calls. `create-t3-app` creates a helper function that abstracts this peculiar API away so that you don't need to import both your NextAuth.js options as well as the `getServerSession` function every time you need to access the session. + +```ts:server/auth.ts +export const getServerAuthSession = (ctx: { + req: GetServerSidePropsContext["req"]; + res: GetServerSidePropsContext["res"]; +}) => { + return getServerSession(ctx.req, ctx.res, authOptions); +}; +``` + +Using this helper function, we can grab the session and pass it through to the tRPC context: + +```ts:server/api/trpc.ts +import { getServerAuthSession } from "../auth"; + +export const createContext = async (opts: CreateNextContextOptions) => { + const { req, res } = opts; + const session = await getServerAuthSession({ req, res }); + return await createContextInner({ + session, + }); +}; +``` + +2. Create a tRPC middleware that checks if the user is authenticated. We then use the middleware in a `protectedProcedure`. Any caller to these procedures must be authenticated, or else an error will be thrown which can be appropriately handled by the client. + +```ts:server/api/trpc.ts +export const protectedProcedure = t.procedure.use(({ 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 }, + }, + }); +}) +``` + +The session object is a light, minimal representation of the user and only contains a few fields. When using the `protectedProcedures`, you have access to the user's id which can be used to fetch more data from the database. + +```ts:server/api/routers/user.ts +const userRouter = router({ + me: protectedProcedure.query(async ({ ctx }) => { + const user = await prisma.user.findUnique({ + where: { + id: ctx.session.user.id, + }, + }); + return user; + }), +}); +``` + +## Usage with Prisma + +Getting NextAuth.js to work with Prisma requires a lot of [initial setup](https://authjs.dev/reference/adapter/prisma/). `create-t3-app` handles all of this for you, and if you select both Prisma and NextAuth.js, you'll get a fully working authentication system with all the required models preconfigured. We ship your scaffolded app with a preconfigured Discord OAuth provider, which we chose because it is one of the easiest to get started with - just provide your tokens in the `.env` and you're good to go. However, you can easily add more providers by following the [NextAuth.js docs](https://next-auth.js.org/providers/). Note that certain providers require extra fields to be added to certain models. We recommend you read the documentation for the provider you would like to use to make sure you have all the required fields. + +### Adding new fields to your models + +When adding new fields to any of the `User`, `Account`, `Session`, or `VerificationToken` models (most likely you'd only need to modify the `User` model), you need to keep in mind that the [Prisma adapter](https://next-auth.js.org/adapters/prisma) automatically creates fields on these models when new users sign up and log in. Therefore, when adding new fields to these models, you must provide default values for them, since the adapter is not aware of these fields. + +If for example, you'd like to add a `role` to the `User` model, you would need to provide a default value to the `role` field. This is done by adding a `@default` value to the `role` field in the `User` model: + +```diff:prisma/schema.prisma ++ enum Role { ++ USER ++ ADMIN ++ } + + model User { + ... ++ role Role @default(USER) + } +``` + +## Usage with Next.js middleware + +Usage of NextAuth.js with Next.js middleware [requires the use of the JWT session strategy](https://next-auth.js.org/configuration/nextjs#caveats) for authentication. This is because the middleware is only able to access the session cookie if it is a JWT. By default, Create T3 App is configured to use the **default** database strategy, in combination with Prisma as the database adapter. + + + Using database sessions is the recommended approach and you should read up on + JWTs before switching to the JWT session strategy to avoid any security + issues. + + +After switching to the JWT session strategy. Make sure to update the `session` callback in `src/server/auth.ts`. +The `user` object will be `undefined`. Instead, retrieve the user's ID from the `token` object. +I.e.: + +```diff:server/auth.ts + export const authOptions: NextAuthOptions = { ++ session: { ++ strategy: "jwt", ++ }, + callbacks: { +- session: ({ session, user }) => ({ ++ session: ({ session, token }) => ({ + ...session, + user: { + ...session.user, +- id: user.id, ++ id: token.sub, + }, + }), + }, + } +``` + +## Setting up the default DiscordProvider + +1. Head to [the Applications section in the Discord Developer Portal](https://discord.com/developers/applications), and click on "New Application" +2. In the settings menu, go to "OAuth2 => General" + +- Copy the Client ID and paste it in `DISCORD_CLIENT_ID` in `.env`. +- Under Client Secret, click "Reset Secret" and copy that string to `DISCORD_CLIENT_SECRET` in `.env`. Be careful as you won't be able to see this secret again, and resetting it will cause the existing one to expire. +- Click "Add Redirect" and paste in `/api/auth/callback/discord` (example for local development: http://localhost:3000/api/auth/callback/discord) +- Save your changes +- It is possible, but not recommended, to use the same Discord Application for both development and production. You could also consider [Mocking the Provider](https://github.com/trpc/trpc/blob/main/examples/next-prisma-websockets-starter/src/pages/api/auth/%5B...nextauth%5D.ts) during development. + +## Useful Resources + +| Resource | Link | +| --------------------------------- | --------------------------------------- | +| NextAuth.js Docs | https://next-auth.js.org/ | +| NextAuth.js GitHub | https://github.com/nextauthjs/next-auth | +| tRPC Kitchen Sink - with NextAuth | https://kitchen-sink.trpc.io/next-auth | diff --git a/www/src/pages/nl/usage/next-js.md b/www/src/pages/nl/usage/next-js.md new file mode 100644 index 0000000000..77bf718134 --- /dev/null +++ b/www/src/pages/nl/usage/next-js.md @@ -0,0 +1,37 @@ +--- +title: Next.js +description: Usage of Next.js +layout: ../../../layouts/docs.astro +lang: en +--- + +Next.js is a backend framework for your React applications. + +
+ +
+ +Check out [Theo's Next.js Conf talk](https://www.youtube.com/watch?v=W4UhNo3HAMw) to get a better understanding of what Next.js is and how it works.

+ +## Why should I use it? + +We love React. It has made UI development accessible in ways we never imagined before. It also can lead developers down some rough paths. Next.js offers a lightly opinionated, heavily optimized approach to creating applications using React. From routing to API definitions to image rendering, we trust Next.js to lead developers towards good decisions. + +Pairing Next.js with [Vercel](https://vercel.com/) makes developing and deploying web apps easier than ever before. Their extremely generous free-tier and super intuitive interface provides a point and click solution to deploy your site (We ❤️ Vercel) + +## Get Static/Server Props + +A key feature of Next.js is its data fetching capabilities. We highly recommend reading through the [official documentation](https://nextjs.org/docs/basic-features/data-fetching) to understand how to use each method and how they differ. `getServerSideProps` is generally discouraged unless there is a good reason for it, due to the fact that it is a blocking call and will slow down your site. [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration) is a great alternative to `getServerSideProps` when the data is dynamic and can be fetched incrementally. + +If you need to use this feature anyway, check these links out: [Advanced tRPC - Callers, functions, and gSSP](https://www.youtube.com/watch?v=G2ZzmgShHgQ) and [SSG-Helpers](https://trpc.io/docs/v9/ssg-helpers) + +## Useful Resources + +| Resource | Link | +| ------------------------------ | ---------------------------------- | +| Next.js Documentation | 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/nl/usage/prisma.md b/www/src/pages/nl/usage/prisma.md new file mode 100644 index 0000000000..fc82701ca0 --- /dev/null +++ b/www/src/pages/nl/usage/prisma.md @@ -0,0 +1,78 @@ +--- +title: Prisma +description: Usage of Prisma +layout: ../../../layouts/docs.astro +lang: en +--- + +Prisma is an ORM for TypeScript, that allows you to define your database schema and models in a `schema.prisma` file, and then generate a type-safe client that can be used to interact with your database from your backend. + +## Prisma Client + +Located at `src/server/db.ts`, the Prisma Client is instantiated as a global variable (as recommended as [best practice](https://www.prisma.io/docs/guides/database/troubleshooting-orm/help-articles/nextjs-prisma-client-dev-practices#problem) by the team at Prisma) and exported to be used in your API routes. We include the Prisma Client in [Context](/en/usage/trpc#-serverapitrpcts) by default and recommend using this instead of importing it separately in each file. + +## Schema + +You will find the Prisma schema file at `/prisma/schema.prisma`. This file is where you define your database schema and models, and is used when generating the Prisma Client. + +### With NextAuth.js + +When you select NextAuth.js in combination with Prisma, the schema file is generated and set up for you with the recommended values for the `User`, `Session`, `Account`, and `VerificationToken` models, as per the [NextAuth.js documentation](https://next-auth.js.org/adapters/prisma). + +## Default Database + +The default database is an SQLite database, which is great for development and quickly spinning up a proof-of-concept but is not recommended for production. You can change the database to use by changing the `provider` in the `datasource` block to either `postgresql` or `mysql`, and then updating the connection string within environment variables to point to your database. + +## Seeding your Database + +[Seeding your database](https://www.prisma.io/docs/guides/database/seed-database) is a great way to quickly populate your database with test data to help you get started. In order to setup seeding, you will need to create a `seed.ts` file in the `/prisma` directory, and then add a `seed` script to your `package.json` file. You'll also need a TypeScript runner that can execute the seed-script. We recommend [tsx](https://github.com/esbuild-kit/tsx), which is a very performant TypeScript runner that uses esbuild and doesn't require any ESM configuration, but `ts-node` or other runners will work as well. + +```jsonc:package.json +{ + "scripts": { + "db-seed": "NODE_ENV=development prisma db seed" + }, + "prisma": { + "seed": "tsx prisma/seed.ts" + } +} +``` + +```ts:prisma/seed.ts +import { db } from "../src/server/db"; + +async function main() { + const id = "cl9ebqhxk00003b600tymydho"; + await db.example.upsert({ + where: { + id, + }, + create: { + id, + }, + update: {}, + }); +} + +main() + .then(async () => { + await db.$disconnect(); + }) + .catch(async (e) => { + console.error(e); + await db.$disconnect(); + process.exit(1); + }); +``` + +Then, just run `pnpm db-seed` (or `npm`/`yarn`) to seed your database. + +## Useful Resources + +| Resource | Link | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Prisma Docs | https://www.prisma.io/docs/ | +| Prisma GitHub | https://github.com/prisma/prisma | +| Prisma Migrate Playground | https://playground.prisma.io/guides | +| 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/nl/usage/tailwind.md b/www/src/pages/nl/usage/tailwind.md new file mode 100644 index 0000000000..bdb355a4b0 --- /dev/null +++ b/www/src/pages/nl/usage/tailwind.md @@ -0,0 +1,96 @@ +--- +title: Tailwind CSS +description: Usage of Tailwind CSS +layout: ../../../layouts/docs.astro +lang: en +--- + +## What is Tailwind CSS? + +Tailwind CSS is a tiny, [utility first](https://tailwindcss.com/docs/utility-first) CSS framework for building custom designs, without the context switching that regular CSS requires. It is purely a CSS framework and does not provide any pre-built components or logic, and provides [a very different set of benefits](https://www.youtube.com/watch?v=CQuTF-bkOgc) compared to a component library like Material UI. + +It makes CSS incredibly easy and quick to write, as shown by the following example: + +Old CSS: + +1. Write CSS, often in a separate file + +```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. Import CSS into your component + +```jsx +import "./my-class.css"; +``` + +3. Add the class to your HTML + +```html +
...
+``` + +Equivalent in Tailwind: + +1. Just write classes in your HTML + +```html +
+ ... +
+``` + +When used together with React Components, it is extremely powerful for quickly building UIs. + +Tailwind CSS has a beautiful built-in design system, that comes out of the box with a carefully chosen color palette, sizing patterns for styles such as width/height and padding/margin for a uniform design, as well as media breakpoints for creating responsive layouts. This design system can be customized and extended to create the exact toolbox of styles that your project needs. + +
+ +
+ +Tru Narla better known as [mewtru](https://twitter.com/trunarla) gave an amazing talk on [building a design system using Tailwind CSS](https://www.youtube.com/watch?v=T-Zv73yZ_QI). + +## Usage + +Make sure you have editor plugins for Tailwind installed to improve your experience writing Tailwind. + +### Extensions and 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) + +### Formatting + +Tailwind CSS classes can easily get a bit messy, so a formatter for the classes is a must have. [Tailwind CSS Prettier Plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) sorts the classes in the [recommended order](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier#how-classes-are-sorted) so that the classes match the outputted css bundle. When selecting Tailwind in the CLI, we will install and configure this for you. + +### Conditionally Applying Classes + +Conditionally adding classes using ternaries can get very messy and hard to read. These packages help in organizing your classes when using some conditional logic. + +- [clsx](https://github.com/lukeed/clsx) +- [classnames](https://github.com/JedWatson/classnames) + +## Useful Resources + +| 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/nl/usage/trpc.md b/www/src/pages/nl/usage/trpc.md new file mode 100644 index 0000000000..6285346d32 --- /dev/null +++ b/www/src/pages/nl/usage/trpc.md @@ -0,0 +1,382 @@ +--- +title: tRPC +description: Usage of tRPC +layout: ../../../layouts/docs.astro +lang: en +--- + +tRPC allows us to write end-to-end typesafe APIs without any code generation or runtime bloat. It uses TypeScript's great inference to infer your API router's type definitions and lets you call your API procedures from your frontend with full typesafety and auto-completion. When using tRPC, your frontend and backend feel closer together than ever before, allowing for an outstanding developer experience. + +
+
+

+ I built tRPC to allow people to move faster by removing the need for 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 + +
+ +
+ +## How do I use tRPC? + +
+ +
+ +tRPC contributor [trashh_dev](https://twitter.com/trashh_dev) made [a killer talk at Next.js Conf](https://www.youtube.com/watch?v=2LYM8gf184U) about tRPC. We highly recommend you watch it if you haven't already. + +With tRPC, you write TypeScript functions on your backend, and then call them from your frontend. A simple tRPC procedure could look like this: + +```ts:server/api/routers/user.ts +const userRouter = createTRPCRouter({ + getById: publicProcedure.input(z.string()).query(({ ctx, input }) => { + return ctx.prisma.user.findFirst({ + where: { + id: input, + }, + }); + }), +}); +``` + +This is a tRPC procedure (equivalent to a route handler in a traditional backend) that first validates the input using Zod (which is the same validation library that we use for [environment variables](./env-variables)) - in this case, it's making sure that the input is a string. If the input is not a string it will send an informative error instead. + +After the input, we chain a resolver function which can be either a [query](https://trpc.io/docs/v10/react-queries), [mutation](https://trpc.io/docs/v10/react-mutations), or a [subscription](https://trpc.io/docs/v10/subscriptions). In our example, the resolver calls our database using our [prisma](./prisma) client and returns the user whose `id` matches the one we passed in. + +You define your procedures in `routers` which represent a collection of related procedures with a shared namespace. You may have one router for `users`, one for `posts`, and another one for `messages`. These routers can then be merged into a single, centralized `appRouter`: + +```ts:server/api/root.ts +const appRouter = createTRPCRouter({ + users: userRouter, + posts: postRouter, + messages: messageRouter, +}); + +export type AppRouter = typeof appRouter; +``` + +Notice that we only need to export our router's type definitions, which means we are never importing any server code on our client. + +Now let's call the procedure on our frontend. tRPC provides a wrapper for `@tanstack/react-query` which lets you utilize the full power of the hooks they provide, but with the added benefit of having your API calls typed and inferred. We can call our procedures from our frontend like this: + +```tsx:pages/users/[id].tsx +import { useRouter } from "next/router"; +import { api } from "../../utils/api"; + +const UserPage = () => { + const { query } = useRouter(); + const userQuery = api.users.getById.useQuery(query.id); + + return ( +
+

{userQuery.data?.name}

+
+ ); +}; +``` + +You'll immediately notice how good the autocompletion and typesafety is. As soon as you write `api.`, your routers will show up in autocomplete, and when you select a router, its procedures will show up as well. You'll also get a TypeScript error if your input doesn't match the validator that you defined on the backend. + +## Inferring errors + +By default, `create-t3-app` sets up an [error formatter](https://trpc.io/docs/error-formatting) that lets you infer your Zod Errors if you get validation errors on the backend. + +Example usage: + +```tsx +function MyComponent() { + const { mutate, error } = api.post.create.useMutation(); + + return ( + { + e.preventDefault(); + const formData = new FormData(e.currentTarget); + mutate({ title: formData.get('title') }); + }}> + + {error?.data?.zodError?.fieldErrors.title && ( + {/** `mutate` returned with an error on the `title` */} + + {error.data.zodError.fieldErrors.title} + + )} + + ... + + ); +} +``` + +## Files + +tRPC requires quite a lot of boilerplate that `create-t3-app` sets up for you. Let's go over the files that are generated: + +### 📄 `pages/api/trpc/[trpc].ts` + +This is the entry point for your API and exposes the tRPC router. Normally, you won't touch this file very much, but if you need to, for example, enable CORS middleware or similar, it's useful to know that the exported `createNextApiHandler` is a [Next.js API handler](https://nextjs.org/docs/api-routes/introduction) which takes a [request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object. This means that you can wrap the `createNextApiHandler` in any middleware you want. See below for an [example snippet](#enabling-cors) of adding CORS. + +### 📄 `server/api/trpc.ts` + +This file is split up in two parts, context creation and tRPC initialization: + +1. We define the context that is passed to your tRPC procedures. Context is data that all of your tRPC procedures will have access to, and is a great place to put things like database connections, authentication information, etc. In create-t3-app we use two functions, to enable using a subset of the context when we do not have access to the request object. + +- `createInnerTRPCContext`: This is where you define context which doesn't depend on the request, e.g. your database connection. You can use this function for [integration testing](#sample-integration-test) or [ssg-helpers](https://trpc.io/docs/v10/ssg-helpers) where you don't have a request object. + +- `createTRPCContext`: This is where you define context which depends on the request, e.g. the user's session. You request the session using the `opts.req` object, and then pass the session down to the `createInnerTRPCContext` function to create the final context. + +2. We initialize tRPC and define reusable [procedures](https://trpc.io/docs/v10/procedures) and [middlewares](https://trpc.io/docs/v10/middlewares). By convention, you shouldn't export the entire `t`-object but instead, create reusable procedures and middlewares and export those. + +You'll notice we use `superjson` as [data transformer](https://trpc.io/docs/v10/data-transformers). This makes it so that your data types are preserved when they reach the client, so if you for example send a `Date` object, the client will return a `Date` and not a string which is the case for most APIs. + +### 📄 `server/api/routers/*.ts` + +This is where you define the routes and procedures of your API. By convention, you [create separate routers](https://trpc.io/docs/v10/server/routers) for related procedures. + +### 📄 `server/api/root.ts` + +Here we [merge](https://trpc.io/docs/v10/merging-routers) all the sub-routers defined in `routers/**` into a single app router. + +### 📄 `utils/api.ts` + +This is the frontend entry point for tRPC. This is where you'll import the router's **type definition** and create your tRPC client along with the react-query hooks. Since we enabled `superjson` as our data transformer on the backend, we need to enable it on the frontend as well. This is because the serialized data from the backend is deserialized on the frontend. + +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. + +Lastly, we export a [helper type](https://trpc.io/docs/v10/infer-types#additional-dx-helper-type) which you can use to infer your types on the frontend. + +
+ +
+ +Create T3 App contributor [Christopher Ehrlich](https://twitter.com/ccccjjjjeeee) made [a video about data flows in tRPC](https://www.youtube.com/watch?v=x4mu-jOiA0Q). This video is recommended if you have used tRPC but still feel a bit unclear about how it works. + +## How do I call my API externally? + +With regular APIs, you can call your endpoints using any HTTP client such as `curl`, `Postman`, `fetch` or straight from your browser. With tRPC, it's a bit different. If you want to call your procedures without the tRPC client, there are two recommended ways to do it: + +### Expose a single procedure externally + +If you want to expose a single procedure externally, you're looking for [server side calls](https://trpc.io/docs/v10/server-side-calls). That would allow you to create a normal Next.js API endpoint, but reuse the resolver part of your tRPC procedure. + +```ts:pages/api/users/[id].ts +import { type NextApiRequest, type NextApiResponse } from "next"; +import { appRouter, createCaller } from "../../../server/api/root"; +import { createTRPCContext } from "../../../server/api/trpc"; + +const userByIdHandler = async (req: NextApiRequest, res: NextApiResponse) => { + // Create context and caller + const ctx = await createTRPCContext({ req, res }); + const caller = 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 occurred + const httpCode = getHTTPStatusCodeFromError(cause); + return res.status(httpCode).json(cause); + } + // Another error occurred + console.error(cause); + res.status(500).json({ message: "Internal server error" }); + } +}; + +export default userByIdHandler; +``` + +### Exposing every procedure as a REST endpoint + +If you want to expose every single procedure externally, checkout the community built plugin [trpc-openapi](https://github.com/jlalmes/trpc-openapi/tree/master). By providing some extra meta-data to your procedures, you can generate an OpenAPI compliant REST API from your tRPC router. + +### It's just HTTP Requests + +tRPC communicates over HTTP, so it is also possible to call your tRPC procedures using "regular" HTTP requests. However, the syntax can be cumbersome due to the [RPC protocol](https://trpc.io/docs/v10/rpc) that tRPC uses. If you're curious, you can check what tRPC requests and responses look like in your browser's network tab, but we suggest doing this only as an educational exercise and sticking to one of the solutions outlined above. + +## Comparison to a Next.js API endpoint + +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: + +```ts:pages/api/users/[id].ts +import { type NextApiRequest, type NextApiResponse } from "next"; +import { prisma } from "../../../server/db"; + +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]); +}; +``` + +Compare this to the tRPC example above and you can see some of the advantages of tRPC: + +- Instead of specifying a url for each route, which can become annoying to debug if you move something, your entire router is an object with autocomplete. +- You don’t need to validate which HTTP method was used. +- 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. +- Instead of creating a response, you can throw errors and return a value or object as you would in any other TypeScript function. +- Calling the procedure on the frontend provides autocompletion and type safety. + +## Useful snippets + +Here are some snippets that might come in handy. + +### Enabling CORS + +If you need to consume your API from a different domain, for example in a monorepo that includes a React Native app, you might need to enable CORS: + +```ts:pages/api/trpc/[trpc].ts +import { type NextApiRequest, type NextApiResponse } from "next"; +import { createNextApiHandler } from "@trpc/server/adapters/next"; +import { appRouter } from "~/server/api/root"; +import { createTRPCContext } from "~/server/api/trpc"; +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: createTRPCContext, + })(req, res); +}; + +export default handler; +``` + +### Optimistic updates + +Optimistic updates are when we update the UI before the API call has finished. This gives the user a better experience because they don't have to wait for the API call to finish before the UI reflects the result of their action. However, apps that value data correctness highly should avoid optimistic updates as they are not a "true" representation of backend state. You can read more on the [React Query docs](https://tanstack.com/query/v4/docs/guides/optimistic-updates). + +```tsx +const MyComponent = () => { + const listPostQuery = api.post.list.useQuery(); + + const utils = api.useUtils(); + const postCreate = api.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(); + }, + }); +}; +``` + +### Sample Integration Test + +Here is a sample integration test that uses [Vitest](https://vitest.dev) to check that your tRPC router is working as expected, the input parser infers the correct type, and that the returned data matches the expected output. + +```ts +import { type inferProcedureInput } from "@trpc/server"; +import { expect, test } from "vitest"; + +import { appRouter, type AppRouter } from "~/server/api/root"; +import { createInnerTRPCContext } from "~/server/api/trpc"; + +test("example router", async () => { + const ctx = await createInnerTRPCContext({ 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" }); +}); +``` + +If your procedure is protected, you can pass in a mocked `session` object when you create the context: + +```ts +test("protected example router", async () => { + const ctx = await createInnerTRPCContext({ + session: { + user: { id: "123", name: "John Doe" }, + expires: "1", + }, + }); + const caller = appRouter.createCaller(ctx); + + // ... +}); +``` + +## Useful Resources + +| Resource | Link | +| ---------------------- | ------------------------------------------------------- | +| tRPC Docs | https://www.trpc.io | +| Bunch of tRPC Examples | 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/nl/usage/typescript.md b/www/src/pages/nl/usage/typescript.md new file mode 100644 index 0000000000..833fd5b2bc --- /dev/null +++ b/www/src/pages/nl/usage/typescript.md @@ -0,0 +1,67 @@ +--- +title: TypeScript +description: Usage of TypeScript +layout: ../../../layouts/docs.astro +lang: en +--- + +
+
+

+ Build safety nets, not guard rails +

+
+ + Avatar of @t3dotgg +
+ Theo - creator of the T3 Stack + + @t3dotgg + +
+ +
+ +Whether you're a new or seasoned developer, we think that TypeScript is a must have. It can look intimidating at first, but much like a lot of tools, is something that many never look back from after starting to use it. + +It provides live feedback as you write your code by defining expected data types, and either provides helpful autocomplete in your code editor, or yells at you with red squiggly lines if you're trying to access a property that doesn't exist or trying to pass a value of the wrong type, which you would otherwise have to debug further down the line. + +It is, perhaps, the tool that provides the most productivity to developers; providing documentation of the code you're writing or consuming directly in your editor, and having instant feedback as you inevitably make mistakes is absolutely priceless. + +## Type Inference + +While many new TypeScript developers are concerned with _writing_ TypeScript, many of its benefits don't actually require you to change your code at all, in particular inference. Inference means that if something is typed, that type will follow it throughout the flow of the application without having to be re-declared in other places. This means that for example once you have defined the types of the arguments that a function takes, the remainder of the function will usually be typesafe without requiring any further TypeScript-specific code. Library developers put a ton of work into maintaining the types for their libraries, which means that we as application developers can benefit from both the inference and the built-in documentation in your code editor that these types provide. + +
+ +
+ +Check out Theo's video on how [you might be using TypeScript wrong](https://www.youtube.com/watch?v=RmGHnYUqQ4k). + +## Powerful uses of type inference + +### Zod + +[Zod](https://github.com/colinhacks/zod) is a schema validation library that is built on top of TypeScript. Write a schema that represents a single source of truth for your data, and Zod will ensure that your data is valid throughout your application, even across network boundaries and external APIs. + +### Tanstack Query + +[Tanstack Query](https://tanstack.com/query/v4/) gives you declarative, always-up-to-date auto-managed queries and mutations that directly improve both your developer and user experiences. + +## Useful Resources + +| 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/nl/why.md b/www/src/pages/nl/why.md new file mode 100644 index 0000000000..0c1cf9e344 --- /dev/null +++ b/www/src/pages/nl/why.md @@ -0,0 +1,50 @@ +--- +title: Why CT3A? +description: Why you should pick Create T3 App for your next project +layout: ../../layouts/docs.astro +lang: en +--- + +We started Create T3 App because [Theo](https://twitter.com/t3dotgg) refused to make a template of his favorite technologies. Inspired by create-next-app, [Astro's CLI](https://astro.build), and a general love for typesafety, the Create T3 App team worked hard to build the best possible starting point for new T3 Stack projects. + +If you're interested in using Next.js in a typesafe way, this is the place to start. If you're curious about any of the specific technology choices we made, read on :) + +## Why TypeScript? + +JavaScript is hard. Why add more rules? + +We firmly believe the experience TypeScript provides will help you be a better developer. It provides live feedback as you write your code by defining expected data types, and either provides helpful autocomplete in your editor or yells at you with red squiggly lines if you're trying to access a property that doesn't exist or trying to pass a value of the wrong type, which you would otherwise have to debug further down the line. Whether you're new to web development or a seasoned pro, the "strictness" of TypeScript will provide a less frustrating, more consistent experience than vanilla JS. + +Typesafety makes you faster. If you're not convinced, you [might be using TypeScript wrong...](https://www.youtube.com/watch?v=RmGHnYUqQ4k) + +## Why Next.js? + +We love React. It has made UI development accessible in ways we never imagined before. It also can lead developers down some rough paths. + +Next.js offers a lightly opinionated, heavily optimized approach to creating applications using React. From routing to API definitions to image rendering, we trust Next.js to lead developers toward good decisions. + +## Why tRPC/Prisma/Tailwind/etc? + +While we believe in keeping things as simple as possible, we find these pieces being used in every "app" like project we build. `create-t3-app` does a great job of letting you adopt the pieces you need. + +### tRPC + +tRPC delivers on GraphQL's promise of seamless client development against a typesafe server without all of the boilerplate. It's a clever abuse of TypeScript that provides an incredible dev experience. + +### Prisma + +Prisma is to SQL what TypeScript is to JS. It created a developer experience that didn't exist before. By generating types from a user-defined schema compatible with [several databases](https://www.prisma.io/docs/concepts/database-connectors), Prisma guarantees end-to-end typesafety from your database to your app. + +Prisma provides a whole [suite of tools](https://www.prisma.io/docs/concepts/overview/should-you-use-prisma#-you-want-a-tool-that-holistically-covers-your-database-workflows) making daily interactions with your database easier. Notably, the Prisma Client is responsible for querying and making SQL so easy you'll barely notice you're using it, and Prisma Studio is a convenient GUI for your database that lets you read and manipulate your data quickly without having to write code. + +### Tailwind CSS + +Tailwind feels like "zen-mode CSS". + +By providing building blocks in the form of good default colors, spacing, and other primitives, Tailwind makes it easy to create a good-looking app. And unlike component libraries, it does not hold you back when you want to take your app to the next level and create something beautiful and unique. + +Additionally, with its inline-like approach, Tailwind encourages you to style without worrying about naming classes, organizing files, or any other issue not directly tied to the problem you're trying to solve. + +### NextAuth.js + +When you want an authentication system in your NextJS application, NextAuth.js is an excellent solution to bring in the complexity of security without the hassle of having to build it yourself. It comes with an extensive list of providers to quickly add OAuth authentication and provides adapters for many databases and ORMs.