Gatsby TypeScript Setup: Configuring GatsbyJS Project with TypeScript Step by Step

🎯 What Will You Learn in This Guide?

In this guide, you'll learn how to catch errors at an early stage and secure your code by integrating your GatsbyJS project with TypeScript.
We explain in simple language all the processes, from the installation of the new Gatsby project to the conversion of components to the .tsx format.

⚙️ 1️⃣ New Gatsby Project Creation and Cleanup

💻 Start Project

gatsby new genixnode-gatsby-ts
cd genixnode-gatsby-ts

➡️ This command creates the basic Gatsby files and gets you ready for development.

🧹 Remove Junk Files

Clean up unused configuration files with the following commands:

rm gatsby-node.js gatsby-browser.js gatsby-ssr.js

➡️ This simplifies your project and makes it ideal for TypeScript integration.

---

📦 2️⃣ Install TypeScript Dependencies

Gatsby has built-in support for TypeScript, but you need to add some type definitions:

npm install --save-dev typescript @types/react @types/react-dom

➡️ This command provides type checking for React and DOM.

🔄 Move JS Files to TSX Format

mv src/components/header.js src/components/header.tsx
mv src/components/layout.js src/components/layout.tsx
mv src/components/seo.js src/components/seo.tsx
mv src/pages/index.js src/pages/index.tsx

➡️ The .tsx extension is mandatory for TypeScript files containing JSX.

---

🧩 3️⃣ TypeScript Compiler Settings (tsconfig.json)

Create tsconfig.json in the project root directory:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "jsx": "preserve",
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["./src/**/*"]
}

➡️ This construct provides strict type checking but does not interfere with Gatsby's Babel compilation.

---

🧠 4️⃣ Rewrite SEO Component with TypeScript

Remove the PropTypes structure in src/components/seo.tsx and recreate it as follows:

import * as React from "react";
import { Helmet } from "react-helmet";
import { useStaticQuery, graphql } from "gatsby";

interface SeoProps {
  description?: string;
  lang?: string;
  meta?: Array<{ name: string; content: string }>;
  title: string;
}

function Seo({ description = '', lang = 'tr', meta = [], title }: SeoProps) {
  const &#123; site &#125;: any = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
          description
          author
        }
      }
    }
  `);

  const metaDescription: string = description || site.siteMetadata.description;
  const defaultTitle: string = site.siteMetadata?.title;

  return (
    <Helmet title={defaultTitle ? `$&#123;title&#125; | $&#123;defaultTitle&#125;` : title}>
      <meta name="description" content=&#123;metaDescription&#125; />
    </Helmet>
  );
}
export default Seo;

➡️ SEO component now works with full type safety.

---

🧱 5️⃣ Transform Layout and Header Components

Layout.tsx

import * as React from "react";
import { useStaticQuery, graphql } from "gatsby";
import Header from "./header";

interface LayoutProps {
  children: React.ReactNode;
}

const Layout = ({ children }: LayoutProps) => {
  const data: any = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
        }
      }
    }
  `);

  const siteTitle: string = data.site.siteMetadata?.title || "Başlık";

  return (
    <>
      <Header siteTitle=&#123;siteTitle&#125; />
      <main>&#123;children&#125;</main>
    </>
  );
};

export default Layout;
Header.tsx
tsx

import * as React from "react";
import &#123; Link &#125; from "gatsby";

interface HeaderProps {
  siteTitle: string;
}

const Header = (&#123; siteTitle &#125;: HeaderProps) => (
  <header style={{ background: "#0069ff", padding: "1rem", textAlign: "center" }}>
    <h1>
      <Link to="/" style={{ color: "white", textDecoration: "none" }}>
        &#123;siteTitle&#125;
      </Link>
    </h1>
  </header>
);

export default Header;

---

🚀 6️⃣ Test the Project

gatsby develop

Run your project by going to http://localhost:8000 in the browser. If there are any type errors, the TypeScript compiler will alert you immediately ✅

---

💬 Frequently Asked Questions (FAQ)

1. Why should TypeScript be preferred?

Because it increases code security by catching errors during the compilation phase.

2. Why is .tsx mandatory?

Because Gatsby components include JSX, .ts is not enough.

3. What does “strict: true” do?

It enables all strict type conventions and improves code quality.

4. When should any type be used?

Temporarily, on ambiguous data types returned from API or GraphQL.

5. How do I deploy on GenixNode?

You can upload the project you prepared from the GenixNode panel with the "Static Site Deployment" tab.

---

🧾 Result

Now your Gatsby project is fully TypeScript supported, error-free and scalable. This structure increases the readability of the code and makes future development easier.