From 380fd66f67226dcd34721ae394c11c7de4f4bc28 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 14 Oct 2021 12:38:36 +0100
Subject: [PATCH] docs: add some info on typescript usage (#1020)

---
 docs/content/2.concepts/2.server-engine.md        |  6 ++++++
 docs/content/2.concepts/3.typescript.md           | 13 +++++++++++++
 .../3.docs/2.directory-structure/17.tsconfig.md   | 15 +++++++++++++++
 3 files changed, 34 insertions(+)
 create mode 100644 docs/content/2.concepts/3.typescript.md
 create mode 100644 docs/content/3.docs/2.directory-structure/17.tsconfig.md

diff --git a/docs/content/2.concepts/2.server-engine.md b/docs/content/2.concepts/2.server-engine.md
index 56d608d985..b1542f2fc4 100644
--- a/docs/content/2.concepts/2.server-engine.md
+++ b/docs/content/2.concepts/2.server-engine.md
@@ -40,6 +40,12 @@ Nitro allows 'direct' calling of routes via the globally-available `$fetch` help
 
 For more information on `$fetch` features, check out [ohmyfetch](https://github.com/unjs/ohmyfetch).
 
+## Typed API routes
+
+When using API routes (or middleware), Nitro will generate typings for these routes as long as you are returning a value instead of using `res.end()` to send a response.
+
+You can access these types when using `$fetch()` or `useFetch()`.
+
 ## Standalone Server
 
 Nitro produces a standalone server dist that is independent of `node_modules`.
diff --git a/docs/content/2.concepts/3.typescript.md b/docs/content/2.concepts/3.typescript.md
new file mode 100644
index 0000000000..ce643a1b43
--- /dev/null
+++ b/docs/content/2.concepts/3.typescript.md
@@ -0,0 +1,13 @@
+# TypeScript
+
+Nuxt 3 is fully typed and provides helpful shortcuts to ensure you have access to accurate type information when you are coding.
+
+## Auto-generated types
+
+When you run `nuxi dev` or `nuxi build`, a `nuxt.d.ts` file will be auto-generated at the root of your project with the types of any modules you are using, as well as the key types that Nuxt 3 requires. Your IDE should recognise these types automatically. It is your choice whether to commit it to version control, but you shouldn't need to do so.
+
+Some of the references in the file are to files that are generated within your `buildDir` (`.nuxt`) and therefore for full typings, you will need to run `nuxi dev` to generate the directory.
+
+::alert{icon=👉}
+Nitro also [auto-generates types](/concepts/server-engine#typed-api-routes) for API routes.
+::
diff --git a/docs/content/3.docs/2.directory-structure/17.tsconfig.md b/docs/content/3.docs/2.directory-structure/17.tsconfig.md
new file mode 100644
index 0000000000..bc3437e37c
--- /dev/null
+++ b/docs/content/3.docs/2.directory-structure/17.tsconfig.md
@@ -0,0 +1,15 @@
+---
+icon: IconFile
+title: tsconfig.json
+head.title: TypeScript configuration file
+---
+
+Nuxt automatically generates a `.nuxt/tsconfig.json` file with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults. You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
+
+```json
+{
+  "extends": "./.nuxt/tsconfig.json"
+}
+```
+
+As you need to, you can customize the contents of this file. However, note that if you need to customize your `paths`, this will completely override the auto-generated path aliases. Instead, it is suggested that you add any path aliases you need to the `alias` property within your `nuxt.config`, where they will get picked up and added to the autogenerated `tsconfig`.