TypeScriptでGatsbyプロジェクトを設定する方法

著者は、 Diversity in Tech Fund を選択して、 Write forDOnationsプログラムの一環として寄付を受け取りました。

序章

TypeScript は、 JavaScript のスーパーセットであり、ビルド時にオプションの静的型付けを追加して、ランタイムエラーのデバッグを削減します。 何年にもわたってJavaScriptの強力な代替手段に成長しました。 同時に、 Gatsby は、静的Webサイトを作成するための便利なフロントエンドフレームワークとして登場しました。 TypeScriptの静的型付け機能は、Gatsbyのような静的サイトジェネレーターとうまく調和し、GatsbyにはTypeScriptでのコーディングのサポートが組み込まれています。

このチュートリアルでは、Gatsbyの組み込み機能を使用して、TypeScript用にGatsbyプロジェクトを構成します。 このチュートリアルの後、TypeScriptをGatsbyプロジェクトに統合する方法を学びます。

前提条件

• 開発環境を実行し、TypeScriptまたはGatsby関連のパッケージをそれぞれ処理するには、Nodeとnpmの両方をインストールする必要があります。 このチュートリアルは、Node.jsバージョン14.17.2およびnpmバージョン6.14.13でテストされました。 macOSまたはUbuntu18.04にインストールするには、Node.jsをインストールしてmacOSにローカル開発環境を作成する方法またはPPAを使用したインストールセクションの手順に従います。 Ubuntu20.04にNode.jsをインストールするには。
• コンピューターにGatsbyCLIコマンドラインツールがインストールされている必要があります。 これを設定するには、最初のギャツビーサイトを設定する方法の冒頭をお読みください。 このチュートリアルは、Gatsbyv3.9.0およびGatsbyCLIv3.9.0でテストされています。
• JavaScript、特にデストラクチャリングやインポート/エクスポートなどのES6+構文に関する十分な知識が必要になります。 これらのトピックの詳細については、 JavaScript での破棄、RESTパラメーター、およびスプレッド構文の理解とJavaScriptでのモジュールとインポートおよびエクスポートステートメントの理解を参照してください。
• さらに、TypeScriptをマシンにインストールする必要があります。 これを行うには、公式TypeScriptWebサイトを参照してください。 Visual Studio Code 以外のエディターを使用している場合は、TypeScriptがビルド時に型チェックを実行し、エラーを表示するようにするために、いくつかの追加手順を実行する必要があります。 たとえば、Atomを使用している場合、真のTypeScriptエクスペリエンスを実現するには、atom-typescriptパッケージをインストールする必要があります。 プロジェクト専用のTypeScriptをダウンロードする場合は、Gatsbyプロジェクトフォルダーを設定した後でダウンロードしてください。

ステップ1—新しいギャツビーサイトの作成とボイラープレートの削除

まず、Gatsbyサイトを作成し、サーバーを実行してサイトを表示できることを確認します。 その後、未使用の定型ファイルとコードをいくつか削除します。 これにより、後の手順で編集できるようにプロジェクトが設定されます。

コンピューターのコンソール/ターミナルを開き、次のコマンドを実行します。

gatsby new gatsby-typescript-tutorial

Gatsbyサイトに必要な定型ファイルとフォルダーを設定するため、実行には数秒かかります。 終了したら、cdをプロジェクトのディレクトリに追加します。

cd gatsby-typescript-tutorial

サイトの開発環境を正しく開始できることを確認するには、次のコマンドを実行します。

gatsby develop

数秒後、コンソールに次のメッセージが表示されます。

Output...
You can now view gatsby-starter-default in the browser.

  http://localhost:8000

通常、デフォルトのポートは:8000ですが、代わりにgatsby develop -p another_numberを実行することでこれを変更できます。

お好みのブラウザに移動し、アドレスバーにhttp://localhost:8000と入力して、サイトを見つけます。 次のようになります。

注：プラグインgatsby-plugin-sharpバージョン3.9.0には既知の問題があり、Gatsbyサイトの構築時に次のエラーが発生する可能性があります。

Output ERROR

ENOENT: no such file or directory, open 'your_file_path/gatsby-typescript-tutorial/.cache/caches/gatsby-plugin-sharp/diskstore-f6dcddbf3c9007cd2587894f75b5cd62.json'

このエラーの回避策は、gatsby-plugin-sharpをバージョン3.8.0にダウングレードすることです。 これを行うには、package.jsonファイルを開き、次の強調表示された変更を行います。

[gatsby-typescript-tutorial/package.json]
...
  "dependencies": {
    "gatsby": "^3.9.0",
    "gatsby-plugin-gatsby-cloud": "^2.9.0",
    "gatsby-plugin-image": "^1.9.0",
    "gatsby-plugin-manifest": "^3.9.0",
    "gatsby-plugin-offline": "^4.9.0",
    "gatsby-plugin-react-helmet": "^4.9.0",
    "gatsby-plugin-sharp": "3.8.0",
    "gatsby-source-filesystem": "^3.9.0",
    "gatsby-transformer-sharp": "^3.9.0",
    "prop-types": "^15.7.2",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "react-helmet": "^6.1.0"
  },
...

ファイルを保存してから、次のコマンドを使用して依存関係を再インストールします。

npm install

次に、GatsbyCLIを使用してpublicおよび.cacheフォルダーを削除し、新しい依存関係リストで再構築できるようにします。

gatsby clean

これで、gatsby developを使用してローカル開発サーバーでGatsbyサイトを開始できるようになります。 このソリューションの詳細については、 GitHubメモリスレッドのエラー：ENOENT：そのようなファイルまたはディレクトリはありませんGatsbyエラーをお読みください。

次に、不要なファイルをすべて削除します。 これには、gatsby-node.js、gatsby-browser.js、およびgatsby-ssr.jsが含まれます。

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

次に、セットアップを完了するために、プロジェクトのインデックスページからボイラープレートコードを削除します。 プロジェクトのルートディレクトリで、srcディレクトリに移動し、次にpagesに移動して、index.jsファイルを開きます。

このチュートリアルでは、<StaticImage />コンポーネントのみを操作するため、h1および[とともに、<Link />コンポーネントに関連するコードを削除できます。 X166X]要素。 ファイルは次のようになります。

gatsby-typescript-tutorial / src / pages / index.js

import * as React from "react"
import { StaticImage } from "gatsby-plugin-image"

import Layout from "../components/layout"
import Seo from "../components/seo"

const IndexPage = () => (
  <Layout>
    <Seo title="Home" />
    <StaticImage
      src="../images/gatsby-astronaut.png"
      width={300}
      quality={95}
      formats={["AUTO", "WEBP", "AVIF"]}
      alt="A Gatsby astronaut"
      style={{ marginBottom: `1.45rem` }}
    />
  </Layout>
)

export default IndexPage

ファイルを保存して閉じます。

プロジェクトを作成し、初期設定を完了したので、必要なプラグインをインストールする準備が整いました。

ステップ2—依存関係のインストール

GatsbyでTypeScriptのサポートを設定するには、このステップでインストールする追加のプラグインと依存関係が必要になります。

gatsby-plugin-typescript プラグインには、新しく作成されたGatsbyサイトがすでに付属しています。 デフォルトのオプションのいずれかを変更する場合を除いて、このプラグインをgatsby-config.jsファイルに明示的に追加する必要はありません。 このGatsbyプラグインを使用すると、TypeScriptで.tsおよび.tsxファイルを作成できます。

アプリはTypeScriptファイルを読み取ることができるため、GatsbyのJavaScriptファイルをTypeScriptファイル拡張子に変更します。 特に、src/componentsのheader.js、layout.js、seo.js、src/pagesのindex.jsをheader.tsx、layout.tsx、seo.tsx、およびindex.tsx：

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

mvコマンドを使用して、ファイルの名前を2番目の引数に変更しています。 .tsxはファイル拡張子です。これらのファイルは、JSXを使用しているためです。

ただし、gatsby-plugin-typescriptプラグインには重要な注意点が1つあります。それは、ビルド時の型チェック（TypeScriptのコア機能）が含まれていないことです。 TypeScriptはVisualStudioでサポートされている言語であるため、VSCodeを使用している場合はこれは問題になりません。 ただし、 Atom などの別のエディターを使用している場合は、完全なTypeScript開発エクスペリエンスを実現するためにいくつかの追加構成を行う必要があります。

GatsbyはReactベースのフレームワークであるため、React関連のタイピングを追加することもお勧めします。 Reactに固有のタイプのタイプチェックを追加するには、次のコマンドを実行します。

npm add @types/react

React DOMに関連する型の型チェックを追加するには、次のコマンドを使用します。

npm add @types/react-dom

プラグインgatsby-plugin-typescriptに慣れてきたので、次のステップでTypeScript用にGatsbyサイトを構成する準備が整いました。

ステップ3—tsconfig.jsonファイルを使用したGatsbyのTypeScriptの構成

このステップでは、tsconfig.jsonファイルを作成します。 tsconfig.jsonファイルには、TypeScriptプロジェクトのルートディレクトリの確立（include）とTypeScriptコンパイラのデフォルト構成のオーバーライド（compilerOptions）の2つの主な目的があります。 このファイルを作成するには、いくつかの方法があります。 tscコマンドラインツールがnpmとともにインストールされている場合は、tsc --initを使用して新しいtsconfigファイルを作成できます。 ただし、ファイルには多くのデフォルトオプションとコメントが入力されます。

代わりに、ディレクトリのルート（gatsby-typescript-project/）に新しいファイルを作成し、tsconfig.jsonという名前を付けます。

次に、compilerOptionsとincludeの2つのプロパティを持つオブジェクトを作成し、次のコードを入力します。

[label gatsby-typescript-tutorial/tsconfig.json] 
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es6",
    "jsx": "preserve",
    "lib": ["dom", "es2015", "es2017"],
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "removeComments": false
  },
  "include": ["./src/**/*"]
}

注：この構成は、gatsby-starter-typescript-plusスターターに部分的に基づいています。

このファイルを保存し、完了したら閉じます。

includeプロパティは、コンパイラがTypeScriptからJavaScriptに変換することを知っているファイル名またはパスの配列を指します。

compilerOptionsで使用される各オプションの簡単な説明は次のとおりです。

• module-プロジェクトのモジュールシステムを設定します。 デフォルトではcommonjsが使用されます。
• target-使用しているJavaScriptのバージョンに応じて、このオプションは、ダウンレベルする機能とそのままにしておく機能を決定します。 これは、プロジェクトが古い環境にデプロイされている場合と、 新しい環境。
• jsx-.tsxファイルでのJSXの処理方法の設定。 preserveオプションは、JSXを変更しません。
• lib-さまざまなJSライブラリ/API（dom、es2015など）の指定された型定義の配列。
• strict-trueに設定すると、ビルド時にTypeScriptのタイプチェック機能が有効になります。
• noEmit-GatsbyはすでにBabelを使用してコードを読み取り可能なJavaScriptにコンパイルしているため、このオプションをtrueに変更して、TypeScriptを除外します。
• isolatedModules-コンパイラ/トランスパイラとしてBabelを選択すると、一度に1つのファイルをコンパイルすることを選択することになり、実行時に問題が発生する可能性があります。 このオプションをtrueに設定すると、この問題が発生しようとしている場合にTypeScriptが警告を表示できます。
• esModuleIterop-このオプションを有効にすると、CommonJS（セットmodule）とESモジュール（カスタム変数と関数のインポートとエクスポート）をより適切に連携させ、すべてのインポートで名前空間オブジェクトを使用できるようになります。
• noUnusedLocalsおよびnoUnusedParamters-これら2つのオプションを有効にすると、未使用のローカル変数またはパラメーターを作成した場合にTypeScriptが通常報告するエラーが無効になります。
• removeComments-これをfalseに設定する（またはまったく設定しない）と、TypeScriptファイルがJavaScriptに変換された後にコメントを表示できます。

tsconfigのTypeScriptのリファレンスガイドにアクセスすると、これらのさまざまなオプションやその他の多くのオプションについて詳しく知ることができます。

TypeScriptがGatsby用に構成されたので、src/componentsおよびsrc/pagesのボイラープレートファイルの一部をリファクタリングして、TypeScript統合を完了します。

ステップ4—TypeScriptのseo.tsxのリファクタリング

このステップでは、TypeScript構文をseo.tsxファイルに追加します。 このステップでは、TypeScriptのいくつかの概念を詳しく説明します。 次のステップでは、他のボイラープレートコードをより簡略化してリファクタリングする方法を示します。

TypeScriptの特徴の1つは、構文の柔軟性です。 変数に明示的に入力を追加したくない場合は、追加する必要はありません。 Gatsbyは、ワークフローにTypeScriptを採用することは「インクリメンタルである可能性があり、インクリメンタルである必要がある」と考えているため、このステップでは3つのコアTypeScriptの概念に焦点を当てます。

• 基本タイプ
• タイプとインターフェースの定義
• ビルド時エラーの処理

TypeScriptの基本的なタイプ

TypeScriptは、boolean、number、およびstringを含む基本データ型をサポートします。 JavaScriptと比較したTypeScriptとの主な構文上の違いは、変数を関連付けられた型で定義できるようになったことです。

たとえば、次のコードブロックは、強調表示されたコードで基本タイプを割り当てる方法を示しています。

let num: number;
num = 0

let str: string;
str = "TypeScript & Gatsby"

let typeScriptIsAwesome: boolean;
typeScriptIsAwesome = true;

このコードでは、numはnumber、strはstring、typeScriptIsAwesomeは[である必要があります。 X104X]。

次に、src/componentsディレクトリにあるseo.tsxファイルのdefaultPropsおよびpropTypes宣言を調べます。 エディターでファイルを開き、次の強調表示された行を探します。

gatsby-typescript-tutorial / src / components / seo.tsx

...
import * as React from "react"
import PropTypes from "prop-types"
import { Helmet } from "react-helmet"
import { useStaticQuery, graphql } from "gatsby"

...
      ].concat(meta)}
    />
  )
}


SEO.defaultProps = {
  lang: `en`,
  meta: [],
  description: ``,
}

SEO.propTypes = {
  description: PropTypes.string,
  lang: PropTypes.string,
  meta: PropTypes.arrayOf(PropTypes.object),
  title: PropTypes.string.isRequired,
}

export default SEO

デフォルトでは、GatsbyサイトのSEOコンポーネントには、PropTypesを使用した弱いタイピングシステムが付属しています。 defaultPropsおよびpropTypesは、インポートされたPropsTypesクラスを使用して、明示的に宣言されます。 たとえば、propTypesオブジェクトのmetaプロップ（またはエイリアス）では、その値はオブジェクトの配列であり、各オブジェクト自体が[ X152X]コンポーネント。 一部の小道具は必須としてマークされていますが（isRequired）、他の小道具はそうではなく、オプションであることを意味します。

TypeScriptを使用しているため、このタイピングシステムを置き換えることになります。 先に進み、defaultPropsとpropTypesを削除します（ファイルの先頭にあるPropTypesのimportステートメントと一緒に）。 ファイルは次のようになります。

[label gatsby-typescript-tutorial/src/components/seo.tsx] 
...
import * as React from "react"
import { Helmet } from "react-helmet"
import { useStaticQuery, graphql } from "gatsby"


...
      ].concat(meta)}
    />
  )
}

export default SEO

デフォルトの入力を削除したので、TypeScriptを使用して型エイリアスを書き出します。

TypeScriptインターフェイスの定義

TypeScriptでは、 interface を使用して、カスタムタイプの「形状」を定義します。 これらは、Reactコンポーネントや関数パラメーターなどの複雑なデータの値型を表すために使用されます。 seo.tsxファイルで、interfaceを作成して、削除されたdefaultPropsおよびpropTypes定義を置き換えます。

次の強調表示された行を追加します。

[label gatsby-typescript-tutorial/src/components/seo.tsx] 
...
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
}

...

インターフェイスSEOPropsは、データ型に関連付けられた各プロパティを設定し、必要に応じて?文字でマークを付けることにより、SEO.propTypesが行ったことを実現します。

関数を入力する

JavaScriptと同様に、関数はTypeScriptアプリケーションで重要な役割を果たします。 渡される引数のデータ型を指定することで、関数を入力することもできます。 seo.tsxファイルで、定義されたSEO関数コンポーネントで作業します。 SEOPropsのインターフェイスが定義された場所で、SEOコンポーネントの関数引数の型を明示的に宣言し、その直後にSEOPropsの戻り型を宣言します。

次の強調表示されたコードを追加します。

gatsby-typescript-tutorial / src / components / seo.tsx

...
interface SEOProps {
  description?: string,
  lang?: string,
  meta?: Array<{name: string, content: string}>,
  title: string
}

function SEO({ description='', lang='en', meta=[], title }: SEOProps) {
  ...
}

ここでは、SEO関数の引数のデフォルトを設定して、それらがインターフェイスに準拠するようにし、: SEOPropsでインターフェイスを追加しました。 以前に定義したSEOPropsインターフェイスで必須プロパティとして定義されているため、SEOコンポーネントに渡される引数のリストに少なくともtitleを含める必要があることに注意してください。 。

最後に、metaDescriptionおよびdefaultTitleの定数宣言を、それらのタイプ（この場合はstring）を設定することで修正できます。

[label gatsby-typescript-tutorial/src/components/seo.tsx] 
...
function SEO({ description='', lang='en', meta=[], title }: SEOProps) {
  const { site } = useStaticQuery(
    graphql`
      query {
        site {
          siteMetadata {
            title
            description
            author
          }
        }
      }
    `
  )
  
  const metaDescription: string = description || site.siteMetadata.description
  const defaultTitle: string = site.siteMetadata?.title
...

TypeScriptのもう1つのタイプは、anyタイプです。 タイプが不明確または定義が難しい変数を扱っている場合は、ビルド時のエラーを回避するための最後の手段としてanyを使用してください。

anyタイプの使用例は、APIリクエストやGraphQLクエリなど、サードパーティからフェッチされたデータを処理する場合です。 分解されたsiteプロパティがGraphQL静的クエリで定義されているseo.tsxファイルで、そのタイプをanyに設定します。

gatsby-typescript-tutorial / src / components / seo.tsx

...
interface SEOProps {
  description?: string,
  lang?: string,
  meta?: Array<{name: string, content: string}>,
  title: string
}

function SEO({ description='', lang='en', meta=[], title }: Props) {
  const { site }: any = useStaticQuery(
    graphql`
      query {
        site {
          siteMetadata {
            title
            description
            author
          }
        }
      }
    `
  )
  ...
}

ファイルを保存して終了します。

定義された値を常にタイプと一致させることが重要です。 それ以外の場合は、TypeScriptコンパイラを介してビルド時エラーが表示されます。

ビルド時エラー

TypeScriptがビルド時にキャッチして報告するエラーに慣れるのに役立ちます。 TypeScriptは、ビルド時にこれらのエラー（主にタイプ関連）をキャッチし、これにより、長期的に（コンパイル時に）デバッグの量を削減するという考え方です。

発生するビルド時エラーの1つの例は、あるタイプの変数を宣言したが、別のタイプの値を割り当てた場合です。 SEOコンポーネントに渡されたキーワード引数の1つの値を別のタイプの1つに変更した場合、TypeScriptコンパイラは不整合を検出してエラーを報告します。 以下は、これがVSCodeでどのように見えるかのイメージです。

エラーはType 'number' is not assignable to type 'string'と表示されます。 これは、interfaceを設定するときに、descriptionプロパティのタイプがstringになると言ったためです。 値0のタイプはnumberです。 descriptionの値を「文字列」に戻すと、エラーメッセージは消えます。

ステップ5—ボイラープレートの残りの部分をリファクタリングする

最後に、TypeScriptを使用して残りのボイラープレートファイルをリファクタリングします：layout.tsxおよびheader.tsx。 seo.tsxと同様に、これらのコンポーネントファイルはsrc/componentsディレクトリにあります。

src/components/layout.tsxを開きます。 下に向かって、定義されたLayout.propTypesです。 次の強調表示された行を削除します。

[label gatsby-typescript-tutorial/src/components/layout.tsx] 
/**
 * Layout component that queries for data
 * with Gatsby's useStaticQuery component
 *
 * See: https://www.gatsbyjs.com/docs/use-static-query/
 */

import * as React from "react"
import PropTypes from "prop-types"
import { useStaticQuery, graphql } from "gatsby"
...

Layout.propTypes = {
  children: PropTypes.node.isRequired,
}

export default Layout

children小道具は、その値がPropTypesクラスごとにタイプnodeであることを示しています。 さらに、それは必須の小道具です。 レイアウトのchildrenは、単純なテキストからReactの子コンポーネントまで何でもかまいません。上部近くにインポートしてインターフェイスに追加することにより、関連するタイプとしてReactNodeを使用します。

次の強調表示された行を追加します。

gatsby-typescript-tutorial / src / components / layout.tsx

...
import * as React from "react"
import { useStaticQuery, graphql } from "gatsby"

import Header from "./header"
import "./layout.css"

interface LayoutProps {
  children: ReactNode
}

const Layout = ({ children }: LayoutProps) => {
  ...

次に、サイトタイトルデータをフェッチするGraphQLクエリを格納するタイプをdata変数に追加します。 このクエリオブジェクトはGraphQLなどのサードパーティエンティティからのものであるため、dataにanyタイプを指定します。 最後に、stringタイプをそのデータで機能するsiteTitle変数に追加します。

[label gatsby-typescript-tutorial/src/components/layout.tsx] 
...
const Layout = ({ children }: LayoutProps) => {
  const data: any = useStaticQuery(graphql`
  query MyQuery {
    site {
      siteMetadata {
        title
      }
    }
  }
`)

const siteTitle: string = data.site.siteMetadata?.title || `Title`

  return (
    <>
      <Header siteTitle={siteTitle} />
      <div
...

ファイルを保存して閉じます。

次に、src/components/header.tsxファイルを開きます。 このファイルには、PropTypesクラスを使用して事前定義されたpropタイプも付属しています。 seo.tsxとlayout.tsxのように、同じプロップ名を使用してHeader.defaultPropsとHeader.propTypesをinterfaceに置き換えます。

gatsby-typescript-tutorial / src / components / header.tsx

import * as React from "react"
import { Link } from "gatsby"

interface HeaderProps {
  siteTitle: string
}

const Header = ({ siteTitle }: HeaderProps) => (
  <header
    style={{
      background: `rebeccapurple`,
      marginBottom: `1.45rem`,
    }}
  >
    <div
      style={{
        margin: `0 auto`,
        maxWidth: 960,
        padding: `1.45rem 1.0875rem`,
      }}
    >
      <h1 style={{ margin: 0 }}>
        <Link
          to="/"
          style={{
            color: `white`,
            textDecoration: `none`,
          }}
        >
          {siteTitle}
        </Link>
      </h1>
    </div>
  </header>
)

export default Header

ファイルを保存して閉じます。

TypeScript用にリファクタリングされたファイルを使用して、サーバーを再起動し、すべてが機能していることを確認できます。 次のコマンドを実行します。

gatsby develop

localhost:8000に移動すると、ブラウザは次のようにレンダリングします。

結論

TypeScriptの静的型付け機能は、デバッグを最小限に抑えるのに大いに役立ちます。 デフォルトでサポートされているため、Gatsbyサイトにも最適な言語です。 Gatsby自体は、ランディングページなどの静的サイトを作成するための便利なフロントエンドツールです。

これで、2つの人気のあるツールを自由に使用できます。 TypeScriptとそれを使ってできることの詳細については、TypeScriptシリーズのコーディング方法をご覧ください。