Typescript - draft of page (#290)

* initial page skeleton

* more stuff on the page

* quick edits

* updated with an example usage

* note about creating manually

* fred pass

Co-authored-by: Fred K. Schott <fkschott@gmail.com>

src/config.ts

@@ -32,6 +32,7 @@ export const SIDEBAR = {
 		{ text: 'Import Aliases', link: 'en/guides/aliases' },
 		{ text: 'Integrations', link: 'en/guides/integrations-guide' },
 		{ text: 'RSS', link: 'en/guides/rss' },
+		{ text: 'TypeScript', link: 'en/guides/typescript' },
 		{ text: 'UI Frameworks', link: 'en/core-concepts/framework-components' },
 		{ text: 'Server-side Rendering (experimental)', link: 'en/guides/server-side-rendering' },
 

src/pages/en/guides/imports.md

@@ -42,10 +42,11 @@ import { getUser } from './user.ts';
 import type { UserType } from './user.ts';
 ```
 
-Astro includes built-in support for TypeScript (`*.ts`) files in your project. TypeScript is automatically transpiled to JavaScript with all type information stripped away.
+Astro includes built-in support for [TypeScript](https://www.typescriptlang.org/). You can import `.ts` and `.tsx` files directly in your Astro project, and even write TypeScript code directly inside your [Astro component](/en/core-concepts/astro-components/#the-component-script). 
 
-Note that Astro builds your TypeScript code but does not perform type checking. Type checking should be taken care of outside of Astro, either by your IDE or through a separate tasks. You can run `tsc --noEmit` in your project to type-check your TypeScript files with the official TypeScript CLI (requires the `typescript` package).
+**Astro doesn't perform any type checking itself.** Type checking should be taken care of outside of Astro, either by your IDE or through a separate script. The [Astro VSCode Extension](/en/editor-setup/) automatically provides TypeScript hints and errors in your open files.
 
+📚 Read more about [TypeScript support in Astro.](/en/guides/typescript/)
 
 ## JSX / TSX
 

src/pages/en/guides/typescript.md

@@ -0,0 +1,83 @@
+---
+layout: ~/layouts/MainLayout.astro
+title: TypeScript
+description: Learn how to use Astro's built-in TypeScript support.
+---
+
+Astro ships with built-in support for [TypeScript](https://www.typescriptlang.org/). You can import `.ts` and `.tsx` files in your Astro project, and even write TypeScript code directly inside your [Astro component](/en/core-concepts/astro-components/#the-component-script). 
+
+Astro doesn't perform any type checking itself. Type checking should be taken care of outside of Astro, either by your IDE or through a separate script. The [Astro VSCode Extension](/en/editor-setup/) automatically provides TypeScript hints and errors in your open files.
+
+## Setup
+
+It is **strongly recommended** that you create a `tsconfig.json` file in your project, so that tools like Astro and VSCode know to understand your project. Some features (like npm package imports) aren't fully supported in TypeScript without a `tsconfig.json` file.
+
+Some TypeScript configuration options require special attention in Astro. Below is our recommended starter `tsconfig.json` file, which you can copy-and-paste into your own project. Every [astro.new template](astro.new) includes this `tsconfig.json` file by default.
+
+```json
+// Example: starter tsconfig.json for Astro projects
+{
+  "compilerOptions": {
+    // Enable top-level await, and other modern ESM features.
+    "module": "ES2022",
+    // Enable node-style module resolution, for things like npm package imports.
+    "moduleResolution": "node",
+    // Enable JSON imports.
+    "resolveJsonModule": true,
+    // Enable stricter transpilation for better output.
+    "isolatedModules": true,
+    // Add Astro-specific type definitions.
+    "types": ["astro/env"]
+  }
+}
+```
+## Type Imports
+
+Use type imports & exports whenever possible. This will help you avoid edge-cases where Astro's bundler may try to incorrectly bundle your imported types as if they were JavaScript.
+
+```diff
+- import { SomeType } from './script';
++ import type { SomeType } from './script';
+```
+
+## Import Aliases
+
+Astro supports [import aliases](/en/guides/aliases/) that you define in your `tsconfig.json` & `jsconfig.json` `paths` configuration. [Read our guide](/en/guides/aliases/) to learn more.
+
+
+```ts
+import HelloWorld from '@components/HelloWorld.astro';
+import Layout from '@layouts/Layout.astro';
+```
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@components/*": ["src/components/*"],
+      "@layouts/*": ["src/layouts/*"]
+    }
+  }
+}
+```
+
+## Component Props
+
+Astro supports typing your component props via TypeScript. To enable, export a TypeScript `Props` interface from your Astro component. The [Astro VSCode Extension](/en/editor-setup/) will automatically look for the `Props` export and give you proper TS support when you use that component inside another template.
+
+```astro
+---
+// Example: HelloWorld.astro
+export interface Props {
+  name: string;
+  greeting?: string;
+}
+const { greeting = 'Hello', name } = Astro.props
+---
+<h2>{greeting}, {name}!</h2>
+```
+
+
+📚 Read more about [`.ts` file imports](/en/guides/imports#typescript) in Astro.  
+📚 Read more about [TypeScript Configuration](https://www.typescriptlang.org/tsconfig).