gatsby config api

November 20, 2021

gatsby config api

gatsby 包含了一個gatsby-config.js，可以提供以下設定：

siteMetaData
plugin
mapping
flags
pathPrefix
polyfill
Proxy
developmentMiddleware

此config檔僅支援commonJs。

siteMetaData

可以定義一些各頁面間共享的參數。gatsby會產生一個 graphQL的 field 叫做 siteMetaData，供各頁面查詢。

module.exports = {
  siteMetadata: {
    title: `Gatsby`,
    siteUrl: `https://www.gatsbyjs.com`,
    description: `Blazing fast modern site generator for React`,
  },
}

plugin

gatsby 不支援直接使用 npm安裝插件。如果要使用gatsby的插件，必須在gatsby-config.js底下定義要使用的插件。

plugin 是一個 Array。可以直接使用string指定要使用的插件名稱：

module.exports = {
  plugins: [`gatsby-plugin-name`],
}

若該插件支援option，也可以傳入包含options的object：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-name`,
      options: {
        optionA: true,
        optionB: `Another option`,
      },
    },
  ],
}

plugin 欄位也可以是混合的 array。可以混合不需要指定option的 plugin (型別為string)以及需要指定option的plugin（型別為object）：

module.exports = {
  plugins: [
    `gatsby-transform-plugin`,
    {
      resolve: `gatsby-plugin-name`,
      options: {
        optionA: true,
        optionB: `Another option`,
      },
    },
  ],
}

flag

設定flag可以指定開啟一些正在實驗中的功能。

pathPrefix

pathPrefix可以加入產生的網頁路由前綴。

Polyfill

gatsbyjs 使用 es6的 promise api。預設為未支援promise的瀏覽器提供了polyfill。如果要提供自已版本的 Promise polyfill，可以將此flag 設為 false。

module.exports = {
  polyfill: false,
}

mapping node type

官方建議使用 @Link grapthQL directives https://www.gatsbyjs.com/docs/reference/graphql-data-layer/schema-customization/#foreign-key-fields

mapping 屬性支援將不同來源的資料做 mapping。

在資料 mapping 前。要先確定是否有裝該資料來源的 transformer (i.e. transformer of yaml, json… )，並且設定gatsby-source-filesystem讓gatsby可以正確取得mapping 檔案。

以下範例，假設一個多作者協同的blog，有一個 author.yaml：

- name: Kyle Mathews
  bio: Founder @ GatsbyJS. Likes tech, reading/writing, founding things. Blogs at bricolage.io.
  twitter: "@kylemathews"

markdown 的 frontmatter：

---
title: A blog post
author: Kyle Mathews
---

設定 author 的 mapping 關係：

module.exports = {
  plugins: [...],
  mapping: {
    "MarkdownRemark.frontmatter.author": `AuthorYaml.name`,
  },
}

gatsby 產生的gruaphql query便提供了兩個資料來源的 mapping 供查詢：

query ($slug: String!) {
  markdownRemark(fields: { slug: { eq: $slug } }) {
    html
    fields {
      slug
    }
    frontmatter {
      title
      author {
        # This now links to the author object
        name
        bio
        twitter
      }
    }
  }
}

mapping 也可以用來mapping 一個包含外來鍵（ids）的array到其它的 collection of data。

例如：

// experement.js
[
  {
    "id": "companyA",
    "company": "Company A",
    "position": "Unicorn Developer",
    "from": "Dec 2016",
    "to": "Present",
    "items": [
      {
        "label": "Responsibility",
        "description": "Being an unicorn"
      },
      {
        "label": "Hands on",
        "tech": ["REACT", "NODE"]
      }
    ]
  }
]

// tech.js
[
  {
    "name": "REACT",
    "icon": "facebook",
    "color": "teal",
    "label": "React"
  },
  {
    "name": "NODE",
    "icon": "server",
    "color": "green",
    "label": "NodeJS"
  }
]

在gatsby-config.js 設定規則：

module.exports = {
  plugins: [...],
  mapping: {
    'ExperienceJson.items.tech': `TechJson.name`
  },
}

可以查詢 tech 與它關聯的項目：

query {
  allExperienceJson {
    edges {
      node {
        company
        position
        from
        to
        items {
          label
          description
          link
          tech {
            label
            color
            icon
          }
        }
      }
    }
  }
}

Proxy

告訴開發server將request導到指定的server。

developMiddleware

加速開發的設定。

jsxRuntime

將此屬性設定為 automatic，可以在開發時直接使用 jsx，而不需手動import react。

jsxImportSource

可以指定gatsby使用特定的jsx transformer。例如若使用 @emotion/react，可以如下設定：

module.exports = {
  jsxImportSource: "@emotion/react",
}

如此預設的 jsx runtime 就會變成 @emotion/react了。