You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To see all of the types available and their generics look at our [TypeScript definition file](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/index.d.ts).
13
15
14
-
## `PageProps`
16
+
## Initializing a new project with TypeScript
17
+
18
+
You can get started with TypeScript and Gatsby by using the CLI:
19
+
20
+
```
21
+
npm init gatsby
22
+
```
23
+
24
+
In the prompts, select TypeScript as your preferred language. You can also pass a `ts` flag to the above command to skip that question and use TypeScript:
You can also write `gatsby-browser` and `gatsby-ssr` in TypeScript. You have the types `GatsbyBrowser` and `GatsbySSR` available to type your API functions. Here are two examples:
71
91
72
92
```tsx:title=gatsby-browser.tsx
73
93
import*asReactfrom"react"
74
-
import { GatsbyBrowser } from"gatsby"
94
+
importtype{ GatsbyBrowser } from"gatsby"
75
95
76
-
exportconst wrapPageElement:GatsbyBrowser["wrapPageElement"] = ({ element }) => {
You can use `GetServerData`, `GetServerDataProps`, and `GetServerDataReturn` for [`getServerData`](/docs/reference/rendering-options/server-side-rendering/).
You can import the type `GatsbyConfig` to type your config object. **Please note:** There are currently no type hints for `plugins` and you'll need to check the [current limitations](#current-limitations) and see if they apply to your `gatsby-config` file.
You can import the type `GatsbyNode` to type your APIs by accessing keys on `GatsbyNode`, e.g. `GatsbyNode["sourceNodes"]`. **Please note:** You'll need to check the [current limitations](#current-limitations) and see if they apply to your `gatsby-node` file.
All the files mentioned above can also be written and used inside a [local plugin](/docs/creating-a-local-plugin/).
223
+
224
+
## `tsconfig.json`
225
+
226
+
Essentially, the `tsconfig.json` file is used in tools external to Gatsby e.g Testing Frameworks like Jest, Code editors and Linting libraries like EsLint to enable them handle TypeScript correctly. You can use the `tsconfig.json` from our [gatsby-minimal-starter-ts](https://github.com/gatsbyjs/gatsby/blob/master/starters/gatsby-starter-minimal-ts/tsconfig.json).
227
+
228
+
## Type Hinting in JS Files
229
+
230
+
You can still take advantage of type hinting in JavaScript files with [JSdoc](https://jsdoc.app/) by importing types directly from Gatsby. You need to use a text exitor that supports those type hints.
[vanilla-extract](https://vanilla-extract.style/) helps you write type‑safe, locally scoped classes, variables and themes. It's a great solution when it comes to styling in your TypeScript project. To use vanilla-extract, select it as your preferred styling solution when initializing your project with `npm init gatsby`. You can also manually setup your project through [gatsby-plugin-vanilla-extract](/plugins/gatsby-plugin-vanilla-extract/) or use the [vanilla-extract example](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-vanilla-extract).
259
+
260
+
## Migrating to TypeScript
261
+
262
+
Gatsby natively supports JavaScript and TypeScript, you can change files from `.js`/`.jsx` to `.ts`/ `tsx` at any point to start adding types and gaining the benefits of a type system. But you'll need to do a bit more to be able use Typescipt in `gatsby-*` files:
263
+
264
+
- Run `gatsby clean` to remove any old artifacts
265
+
- Convert your `.js`/`.jsx` files to `.ts/.tsx`
266
+
- Install `@types/node`, `@types/react`, `@types/react-dom`, `typescript` as `devDependencies`
267
+
- Add a `tsconfig.json` file using `npx tsc init` or use the one from [gatsby-minimal-starter-ts](https://github.com/gatsbyjs/gatsby/blob/master/starters/gatsby-starter-minimal-ts/tsconfig.json)
268
+
- Rename `gatsby-*` files:
269
+
-`gatsby-node.js` to `gatsby-node.ts`
270
+
-`gatsby-config.js` to `gatsby-config.ts`
271
+
-`gatsby-browser.js` to `gatsby-browser.tsx`
272
+
-`gatsby-ssr.js` to `gatsby-ssr.tsx`
273
+
- Address any of the [current limitations](#current-limitations)
274
+
275
+
## Current limitations
276
+
277
+
There are some limitations currently that you need to be aware of. We'll do our best to mitigate them in our code or through contributions to upstream dependencies.
278
+
279
+
### Parcel TypeScript features
280
+
281
+
Parcel is used for the compilation and it currently has [limitations on TypeScript features](https://parceljs.org/languages/typescript/), namely:
282
+
283
+
- No support for `baseUrl` or `paths` inside `tsconfig.json`
284
+
- It implicitly enables the [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules) option by default
285
+
286
+
### `__dirname`
287
+
288
+
You can't use `__dirname` and `__filename` in your files. You'll need to replace these instances with a `path.resolve` call. Example diff for a `gatsby-config` file:
289
+
290
+
```diff
291
+
+ import path from "path"
292
+
293
+
const config = {
294
+
plugins: [
295
+
{
296
+
resolve: `gatsby-source-filesystem`,
297
+
options: {
298
+
name: `your-name`,
299
+
+ path: path.resolve(`some/folder`),
300
+
- path: `${__dirname}/some/folder`,
301
+
},
302
+
},
303
+
]
304
+
}
305
+
306
+
export default config
307
+
```
308
+
309
+
Progress on this is tracked in [Parcel #7611](https://github.com/parcel-bundler/parcel/issues/7611).
310
+
311
+
### `require.resolve`
312
+
313
+
You can't use `require.resolve` in your files. You'll need to replace these instances with a `path.resolve` call. Example diff for a `gatsby-node` file:
Progress on this is tracked in [Parcel #6925](https://github.com/parcel-bundler/parcel/issues/6925).
323
+
324
+
### Other
325
+
326
+
- Workspaces (e.g. Yarn) are not supported yet.
327
+
- When changing `siteMetadata` in `gatsby-config` no hot-reloading will occur during `gatsby develop`. A restart is needed at the moment.
328
+
329
+
## Other Resources
137
330
138
-
TypeScript integration is supported through automatically including [`gatsby-plugin-typescript`](/plugins/gatsby-plugin-typescript/). Visit that link to see configuration options and limitations of this setup.
331
+
TypeScript integration for pages is supported through automatically including [`gatsby-plugin-typescript`](/plugins/gatsby-plugin-typescript/). Visit that link to see configuration options and limitations of this setup.
139
332
140
333
If you are new to TypeScript, check out these other resources to learn more:
Copy file name to clipboardExpand all lines: docs/docs/tutorial/part-1/index.mdx
+20-6
Original file line number
Diff line number
Diff line change
@@ -58,7 +58,7 @@ To create your first Gatsby site, you're going to use a command from the Gatsby
58
58
59
59
<Announcementstyle={{marginBottom: "1.5rem"}}>
60
60
61
-
**Note:** For this Tutorial, your Gatsby CLI should be v3 or newer. To check what version you have installed, run the following command:
61
+
**Note:** For this Tutorial, your Gatsby CLI should be v4.8 or newer. To check what version you have installed, run the following command:
62
62
63
63
```shell
64
64
gatsby --version
@@ -106,7 +106,21 @@ What would you like to name the folder where your site will be created?
106
106
✔ Desktop/ my-first-gatsby-site
107
107
```
108
108
109
-
5. When the prompt asks, **"Will you be using a CMS?"** select **"No (or I'll add it later)"**.
109
+
5. When the prompt asks, **"Will you be using JavaScript or TypeScript?"** choose **JavaScript**.
110
+
111
+
```shell
112
+
Will you be using JavaScript or TypeScript?
113
+
❯ JavaScript
114
+
TypeScript
115
+
```
116
+
117
+
<Announcementstyle={{marginBottom: "1.5rem"}}>
118
+
119
+
This tutorial doesn't require any prior TypeScript knowledge as it uses JavaScript. If you're familiar with TypeScript you can read the [Gatsby and TypeScript guide](/how-to/custom-configuration/typescript/) to learn about typings, files, and conventions. If you want to use TypeScript we recommend going through the tutorial first and then only afterwards convert the project to TypeScript.
120
+
121
+
</Announcement>
122
+
123
+
6. When the prompt asks, **"Will you be using a CMS?"** select **"No (or I'll add it later)"**.
110
124
111
125
```shell
112
126
✔ Will you be using a CMS?
@@ -121,21 +135,21 @@ But in this first site, you'll set things up manually to learn about how Gatsby'
121
135
122
136
</Announcement>
123
137
124
-
6. When the prompt asks, **"Would you like to install a styling system?"**select**"No (or I'll add it later)"**. (You'll add styles manually later.)
138
+
7. When the prompt asks, **"Would you like to install a styling system?"**select**"No (or I'll add it later)"**. (You'll add styles manually later.)
125
139
126
140
```shell
127
141
✔ Would you like to install a styling system?
128
142
· No (or I'll add it later)
129
143
```
130
144
131
-
7. When the prompt asks, **"Would you like to install additional features with other plugins?"** use the arrow and Enter keys to select **"Done"**.
145
+
8. When the prompt asks, **"Would you like to install additional features with other plugins?"** use the arrow and Enter keys to select **"Done"**.
132
146
133
147
```shell
134
148
✔ Would you like to install additional features with other plugins?
135
149
· Done
136
150
```
137
151
138
-
8. The prompt will show you a summary of what `gatsby new` will do. It should look something like the output below.
152
+
9. The prompt will show you a summary of what `gatsby new` will do. It should look something like the output below.
139
153
140
154
```shell
141
155
Thanks! Here's what we'll now do:
@@ -146,7 +160,7 @@ Thanks! Here's what we'll now do:
146
160
? Shall we do this? (Y/n) › Yes
147
161
```
148
162
149
-
9. When the prompt asks, **"Shall we do this?"** enter **"Y"**. The `gatsby new` command will start building your site. Your internet download speed will affect how long this command takes to run. After it finishes, you should see a message like this:
163
+
10. When the prompt asks, **"Shall we do this?"** enter **"Y"**. The `gatsby new` command will start building your site. Your internet download speed will affect how long this command takes to run. After it finishes, you should see a message like this:
150
164
151
165
```shell
152
166
🎉 Your new Gatsby site My First Gatsby Site has been successfully
0 commit comments