docs: write some docs (#323)

* docs: change description and add nexxel's website in package.json * docs: add faq page * docs: add tutorials to generated readme * docs: rename getting started to t3 axioms and add advanced usage * docs: add me3 in t3 collection * docs: make p capital * docs: update contributing guide * docs: update link to t3 axiom in faq * docs: fix link to docs in navbar * docs: update contributing guide, can't add dev script for cli * docs: dark theme by default * chore: add some scripts * docs: add scripts to contributing guide Co-authored-by: Julius Marminge <[email protected]>
t3-oss · Aug 17, 2022 · 86fd3d6 · 86fd3d6 · vercel · Aug 17, 2022
1 parent 3a74fd9
commit 86fd3d6
Show file tree

Hide file tree

Showing 10 changed files with 175 additions and 27 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -41,17 +41,23 @@ pnpm install
 
 ### Implement your changes
 
-Now you're all setup and can start implementing your changes.
-
-When you want to test your changes, run:
-
-```bash
-pnpm dev
-```
-
-which will build and start the CLI.
-
-When making commits, make sure to follow the [convential commit](https://www.conventionalcommits.org/en/v1.0.0/) guidelines, i.e. prepending the message with `feat:`, `fix:`, `chore:` etc...
+This project is a [Turborepo](https://turborepo.org/) monorepo. The code for the CLI is in the `cli` directory, and the docs is in the `www` directory. Now you're all setup and can start implementing your changes.
+
+Here are some useful scripts for when you are developing:
+
+| Command          | Description                                             |
+| ---------------- | ------------------------------------------------------- |
+| `pnpm dev:cli`   | Builds and starts the CLI in watch-mode                 |
+| `pnpm dev:www`   | Starts the development server for the docs with HMR     |
+| `pnpm build:cli` | Builds the CLI                                          |
+| `pnpm build:www` | Builds the docs                                         |
+| `pnpm build`     | Builds CLI and docs                                     |
+| `pnpm format`    | Formats the code                                        |
+| `pnpm lint`      | Lints the code                                          |
+| `pnpm lint:fix`  | Lints the code and fixes any errors                     |
+| `pnpm check`     | Checks your code for typeerrors, formatting and linting |
+
+When making commits, make sure to follow the [convential commit](https://www.conventionalcommits.org/en/v1.0.0/) guidelines, i.e. prepending the message with `feat:`, `fix:`, `chore:`, `docs:`, etc...
 
 ### When you're done
 

diff --git a/cli/template/base/README.md b/cli/template/base/README.md
@@ -19,6 +19,13 @@ If you are not familiar with the different technologies used in this project, pl
 - [TailwindCSS](https://tailwindcss.com)
 - [tRPC](https://trpc.io) (using @next version? [see v10 docs here](https://alpha.trpc.io))
 
+Also checkout these awesome tutorials on `create-t3-app`.
+
+- [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)
+- [Build a full stack app with create-t3-app](https://www.nexxel.dev/blog/ct3a-guestbook)
+- [A first look at create-t3-app](https://dev.to/ajcwebdev/a-first-look-at-create-t3-app-1i8f)
+
 ## How do I deploy this?
 
 ### Vercel

diff --git a/package.json b/package.json
@@ -1,8 +1,8 @@
 {
   "name": "@ct3a/root",
   "version": "0.0.0",
-  "description": "Create web application with the t3 stack",
-  "author": "Shoubhit Dash <[email protected]>",
+  "description": "Quickest way to start a new web app with full stack typesafety",
+  "author": "Shoubhit Dash <[email protected]> (https://nexxel.dev)",
   "maintainers": [
     "Julius Marminge <[email protected]> (https://jumr.dev)"
   ],
@@ -26,9 +26,13 @@
   },
   "scripts": {
     "typecheck": "turbo run typecheck",
+    "build:cli": "turbo run build --filter create-t3-app",
+    "build:www": "turbo run build --filter www",
     "build": "turbo run build",
-    "dev": "turbo run dev",
-    "start": "turbo run start",
+    "start:cli": "pnpm run start --filter create-t3-app",
+    "start:www": "turbo run start --filter www",
+    "dev:cli": "pnpm --filter create-t3-app dev",
+    "dev:www": "turbo run dev --filter=www",
     "lint": "eslint . --cache --cache-strategy content",
     "lint:fix": "pnpm lint --fix",
     "format": "prettier --write --plugin-search-dir=. \"**/*.{ts,tsx,md,mdx,json,js,mjs,cjs,astro}\"",

diff --git a/turbo.json b/turbo.json
@@ -4,6 +4,9 @@
       "outputs": ["dist/**"],
       "dependsOn": ["^build"]
     },
+    "start": {
+      "dependsOn": ["^build"]
+    },
     "lint": {
       "outputs": []
     },

diff --git a/www/docs/faq.md b/www/docs/faq.md
@@ -4,3 +4,116 @@ title: FAQ
 sidebar_label: FAQ
 slug: /faq
 ---
+
+Here are some commonly asked questions about `create-t3-app`.
+
+## Why are there `.js` files in the project?
+
+As per [T3-Axiom #3](/docs/t3-axioms#typesafety-isnt-optional), we take 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 its 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 `@ts-check` comment at the top.
+
+## 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 the most basic configuration and then move on to more advanced configuration.
+
+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-Auth.js](https://next-auth.js.org)
+- [Prisma](https://prisma.io)
+- [TailwindCSS](https://tailwindcss.com)
+- [tRPC](https://trpc.io) (using @next version? [see v10 docs here](https://alpha.trpc.io))
+
+Also checkout these awesome tutorials on `create-t3-app`.
+
+- [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)
+- [Build a full stack app with create-t3-app](https://www.nexxel.dev/blog/ct3a-guestbook)
+- [A first look at create-t3-app](https://dev.to/ajcwebdev/a-first-look-at-create-t3-app-1i8f)
+
+## How do I deploy this?
+
+### Vercel
+
+We recommend deploying to [Vercel](https://vercel.com/?utm_source=t3-oss&utm_campaign=oss). It makes it super easy to deploy NextJs apps.
+
+- Push your code to a GitHub repository.
+- Go to [Vercel](https://vercel.com/?utm_source=t3-oss&utm_campaign=oss) and sign up with GitHub.
+- Create a Project and import the repository you pushed your code to.
+- Add your environment variables.
+- Click **Deploy**
+- Now whenever you push a change to your repository, Vercel will automatically redeploy your website!
+
+### Docker
+
+You can also dockerize this stack and deploy a container.
+
+1. In your [next.config.mjs](./next.config.mjs), add the `output: "standalone"` option to your config.
+
+2. Create a `.dockerignore` file with the following contents:
+
+   ```
+   Dockerfile
+   .dockerignore
+   node_modules
+   npm-debug.log
+   README.md
+
+   .next
+   .git
+   ```
+
+3. Create a `Dockerfile` with the following contents:
+
+   ```Dockerfile
+   # Install dependencies only when needed
+   FROM node:16-alpine AS deps
+   # Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
+   RUN apk add --no-cache libc6-compat
+   WORKDIR /app
+   # Install dependencies based on the preferred 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
+   # Rebuild the source code only when needed
+   FROM node:16-alpine AS builder
+   WORKDIR /app
+   COPY --from=deps /app/node_modules ./node_modules
+   COPY . .
+   # Next.js collects completely anonymous telemetry data about general usage.
+   # Learn more here: https://nextjs.org/telemetry
+   # Uncomment the following line in case you want to disable telemetry during the build.
+   # ENV NEXT_TELEMETRY_DISABLED 1
+   RUN yarn build
+
+   # If using npm comment out above and use below instead
+   # RUN npm run build
+   # Production image, copy all the files and run next
+   FROM node:16-alpine AS runner
+
+   WORKDIR /app
+   ENV NODE_ENV production
+   # Uncomment the following line in case you want to disable telemetry during runtime.
+   # ENV NEXT_TELEMETRY_DISABLED 1
+   RUN addgroup --system --gid 1001 nodejs
+   RUN adduser --system --uid 1001 nextjs
+   # You only need to copy next.config.js if you are NOT using the default configuration
+   # COPY --from=builder /app/next.config.js ./
+   COPY --from=builder /app/public ./public
+   COPY --from=builder /app/package.json ./package.json
+   # Automatically leverage output traces to reduce image size
+   # https://nextjs.org/docs/advanced-features/output-file-tracing
+   COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+   COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+   USER nextjs
+   EXPOSE 3000
+   ENV PORT 3000
+   CMD ["node", "server.js"]
+   ```
+
+4. You can now build an image to deploy yourself, or use a PaaS such as [Railway's](https://railway.app) automated [Dockerfile deployments](https://docs.railway.app/deploy/dockerfiles) to deploy your app.
diff --git a/www/docs/installation.md b/www/docs/installation.md
@@ -25,6 +25,15 @@ yarn create t3-app
 pnpm dlx create-t3-app@latest
 ```
 
+## 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 use all default options to bootstrap a new t3-app    |
+| `--noInstall`     | Generate project without installing dependencies                        |
+
 ## Experimental
 
 If you prefer using the [experimental v10 version of tRPC](https://alpha.trpc.io/), use `create-t3-app@next`. Note that the alpha versions of tRPC that it uses may contain API changes. We will try our best to keep on top of these, please file an issue if we have missed something.

diff --git a/www/docs/getting-started.md → www/docs/t3-axioms.md b/www/docs/getting-started.md → www/docs/t3-axioms.md
@@ -1,8 +1,8 @@
 ---
-id: getting-started
-title: Getting started on your T3 App
-sidebar_label: Getting started
-slug: /getting-started
+id: t3-axioms
+title: The T3 Axioms
+sidebar_label: T3 Axioms
+slug: /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.

diff --git a/www/docs/t3-collection.md b/www/docs/t3-collection.md
@@ -7,14 +7,15 @@ slug: /t3-collection
 
 ## Open Source apps made using the T3 Stack
 
-| Description                      | Repo                                                                  | Link                             |
-| -------------------------------- | --------------------------------------------------------------------- | -------------------------------- |
-| Zapdos - a QnA app for streamers | [t3-oss/zapdos](https://github.com/t3-oss/zapdos)                     | [z.t3.gg](https://z.t3.gg)       |
-| nexxeln's personal site          | [nexxeln/nexxel.dev](https://github.com/nexxeln/nexxel.dev)           | [nexxel.dev](https://nexxel.dev) |
-| Julius' personal site            | [juliusmarminge/jumr.dev](https://github.com/juliusmarminge/jumr.dev) | [jumr.dev](https://jumr.dev)     |
+| Description                                                      | Repo                                                                  | Link                             |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------- |
+| Zapdos - a QnA app for streamers                                 | [t3-oss/zapdos](https://github.com/t3-oss/zapdos)                     | [z.t3.gg](https://z.t3.gg)       |
+| nexxel's personal site                                           | [nexxeln/nexxel.dev](https://github.com/nexxeln/nexxel.dev)           | [nexxel.dev](https://nexxel.dev) |
+| Julius' personal site                                            | [juliusmarminge/jumr.dev](https://github.com/juliusmarminge/jumr.dev) | [jumr.dev](https://jumr.dev)     |
+| Me3 - Describe yourself in 3 things and share with your friends. | [hnqg/me3](https://github.com/hnqg/me3)                               | [me.hnqg.io](https://me.hnqg.io) |
 
 ## Companies using the T3 Stack
 
 | Company | Link                       |
 | ------- | -------------------------- |
-| ping.gg | [ping.gg](https://ping.gg) |
+| Ping.gg | [ping.gg](https://ping.gg) |
diff --git a/www/docusaurus.config.js b/www/docusaurus.config.js
@@ -38,6 +38,11 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     {
+      colorMode: {
+        defaultMode: "dark",
+        disableSwitch: false,
+        respectPrefersColorScheme: false,
+      },
       navbar: {
         title: "Create T3 App",
         logo: {
@@ -46,7 +51,7 @@ const config = {
         },
         items: [
           {
-            to: "docs/intro",
+            to: "docs/introduction",
             label: "Docs",
           },
           {

diff --git a/www/sidebars.js b/www/sidebars.js
@@ -8,7 +8,7 @@ const sidebars = {
       label: "Introduction",
       items: [
         "introduction",
-        "getting-started",
+        "t3-axioms",
         "installation",
         "why",
         "faq",