{"id":28052,"date":"2021-06-24T14:29:10","date_gmt":"2021-06-24T14:29:10","guid":{"rendered":"http:\/\/How-to-build-a-Gatsby-Image-Gallery-Theme"},"modified":"2021-06-24T14:29:10","modified_gmt":"2021-06-24T14:29:10","slug":"how-to-build-a-gatsby-image-gallery-theme","status":"publish","type":"post","link":"https:\/\/cloudinary.com\/blog\/guest_post\/how-to-build-a-gatsby-image-gallery-theme\/","title":{"rendered":"How to build a Gatsby Image Gallery Theme"},"content":{"rendered":"

In this media jam, we will build a Gatsby Theme<\/a> for an Image Gallery<\/a>. The images will be stored and fetched from Cloudinary. We will conclude this jam by publishing our theme to the npm registry.<\/p>\n

If you want to jump right into the code, check out the GitHub Repo here<\/a> and the NPM package here<\/a>.<\/p>\n

Code Sandbox<\/h2>\n<\/div>\n \n
\n <\/iframe>\n <\/div>\n\n

What are Gatsby Themes?<\/h2>\n

Gatsby Themes<\/a> are plugins that include a gatsby-config.js<\/code> file and pre-configured functionalities, UI design. These themes are Node.js packages that implement Gatsby APIs and are commonly installed through a registry like npm<\/code>.<\/p>\n

How to setup Yarn workspace<\/h2>\n

Make sure you have yarn<\/code> installed on your local dev machine. You can read more about yarn installation here<\/a>.<\/p>\n

You will also need to install the Gatsby command-line tool (CLI). The gatsby-cli<\/code> is the main entry point for getting up and running with a Gatsby application. You can read more about gatsby-cli<\/code> here<\/a>.<\/p>\n

Run the following command in the terminal to install yarn<\/code> and gatsby-cli<\/code> globally.<\/p>\n

npm install --global<\/span> yarn\nnpm install -g gatsby-cli\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n
Run the following command to create a package.json<\/code> in your root directory.<\/p>\n
touch<\/span> package<\/span>.json<\/span>\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n
Add the following code to package.json<\/code>.<\/p>\n
{\n    \"private\"<\/span>: true<\/span>,\n    \"workspaces\"<\/span>: [\"gatsby-theme-cloudinary-gallery\"<\/span>, \"demo\"<\/span>]\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n
You will create two workspaces named gatsby-theme-cloudinary-gallery<\/code> and demo<\/code>. Here gatsby-theme-cloudinary-gallery<\/code> is the Gatsby Theme, and the demo<\/code> is the Gatsby site to test the theme.<\/p>\n
The gatsby-theme-cloudinary-gallery<\/code> will be installed as a dependency in the demo<\/code> workspace to test the theme before publishing it to the npm registry.<\/p>\n
Run the following command in your project\u2019s root directory.<\/p>\n
mkdir gatsby-theme-cloudinary-gallery\nmkdir demo\ncd gatsby-theme-cloudinary-gallery\nnpm init -y\ncd ..\ncd demo\nnpm init -y\ncd ..\n<\/code><\/span><\/pre>\n
The above commands will create two directories named gatsby-theme-cloudinary-gallery<\/code> and demo<\/code>\u2014each with a package.json<\/code> in it.<\/p>\n
Your file tree will look like this.<\/p>\n
.\n\u251c\u2500\u2500 gatsby-theme-cloudinary-gallery\n\u2502   \u2514\u2500\u2500 package.json\n\u251c\u2500\u2500 demo\n\u2502   \u2514\u2500\u2500 package.json\n\u2514\u2500\u2500 package.json\n<\/code><\/pre>\n
Update gatsby-theme-cloudinary-gallery\/package.json<\/code> like this.<\/p>\n
{\n    \"name\"<\/span>: \"gatsby-theme-cloudinary-gallery\"<\/span>,\n    \"version\"<\/span>: \"1.0.0\"<\/span>,\n    \"description\"<\/span>: \"\"<\/span>,\n    \"main\"<\/span>: \"index.js\"<\/span>,\n    \"scripts\"<\/span>: {\n        \"build\"<\/span>: \"gatsby build\"<\/span>,\n        \"develop\"<\/span>: \"gatsby develop\"<\/span>,\n        \"clean\"<\/span>: \"gatsby clean\"<\/span>\n    },\n    \"keywords\"<\/span>: [\n        \"gatsby\"<\/span>,\n        \"gatsby-theme\"<\/span>,\n        \"gatsby-plugin\"<\/span>,\n        \"react\"<\/span>,\n        \"images\"<\/span>,\n        \"cloudinary\"<\/span>,\n        \"gallery\"<\/span>,\n        \"cloudinary-gallery\"<\/span>\n],\n    \"author\"<\/span>: \"\"<\/span>,\n    \"license\"<\/span>: \"MIT\"<\/span>\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n
Inside the gatsby-theme-cloudinary-gallery<\/code> directory, create a file named index.js<\/code>. Run the following command to create it.<\/p>\n
touch gatsby-theme-cloudinary-gallery\/index.js\n<\/code><\/span><\/pre>\n
This file is needed since it is present as the main entry point in the package.json<\/code>. You can leave it empty for now; you will update it in the last section to export the Gallery<\/code> component.<\/p>\n
Update demo\/package.json<\/code> like this.<\/p>\n
{\n    \"name\"<\/span>: \"demo\"<\/span>,\n    \"version\"<\/span>: \"1.0.0\"<\/span>,\n    \"description\"<\/span>: \"\"<\/span>,\n    \"main\"<\/span>: \"index.js\"<\/span>,\n    \"scripts\"<\/span>: {\n        \"build\"<\/span>: \"gatsby build\"<\/span>,\n        \"develop\"<\/span>: \"gatsby develop\"<\/span>,\n        \"clean\"<\/span>: \"gatsby clean\"<\/span>\n    },\n    \"keywords\"<\/span>: [],\n    \"author\"<\/span>: \"\"<\/span>,\n    \"license\"<\/span>: \"MIT\"<\/span>\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n
Run the following command to add dependencies to the gatsby-theme-cloudinary-gallery<\/code> and demo<\/code> workspace.<\/p>\n
yarn workspace demo add gatsby react react-dom gatsby-theme-cloudinary-gallery@*\nyarn workspace gatsby-theme-cloudinary-gallery add -P gatsby react react-dom\nyarn workspace gatsby-theme-cloudinary-gallery add -D gatsby react react-dom\n<\/code><\/span><\/pre>\n
You install gatsby<\/code>, react<\/code>, and react-dom<\/code> in the demo<\/code> workspace to set up a Gatsby site. You also install the gatsby-theme-cloudinary-gallery<\/code> in the demo<\/code> workspace as a dependency.<\/p>\n
In the gatsby-theme-cloudinary-gallery<\/code> workspace, you install gatsby<\/code>, react<\/code>, and react-dom<\/code> as both dev dependencies and peer dependencies.<\/p>\n
Dev dependencies are the packages you need during project development.<\/p>\n
Peer dependencies are used to specify that your package is compatible with a specific version of the npm package.<\/p>\n
During installation, if the package already exists in the node_modules<\/code> directory, it will do nothing. But if it is not present, a warning will be shown to the user.<\/p>\n
Since gatsby<\/code>, react<\/code>, and react-dom<\/code> will be present in every Gatsby site, it is unlikely that this warning will be shown to the user.<\/p>\n
Run the following command to check demo<\/code> is using the gatsby-theme-cloudinary-gallery<\/code> from the workspace.<\/p>\n
yarn workspaces info\n<\/code><\/span><\/pre>\n
You should see an output similar to this.<\/p>\n
{\n  \"gatsby-theme-cloudinary-gallery\"<\/span>: {\n    \"location\"<\/span>: \"gatsby-theme-cloudinary-gallery\"<\/span>,\n    \"workspaceDependencies\"<\/span>: [],\n    \"mismatchedWorkspaceDependencies\"<\/span>: []\n  },\n  \"demo\"<\/span>: {\n    \"location\"<\/span>: \"demo\"<\/span>,\n    \"workspaceDependencies\"<\/span>: [\n      **\"gatsby-theme-cloudinary-gallery\"<\/span>**\n    ],\n    \"mismatchedWorkspaceDependencies\"<\/span>: []\n  }\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n
In this jam, you will use Tailwind CSS to style your theme. Run the following command to install it.<\/p>\n
\nyarn<\/span> workspace<\/span> gatsby-theme-cloudinary-gallery<\/span> add<\/span> gatsby-plugin-postcss<\/span> tailwindcss<\/span>@latest<\/span> postcss@latest autoprefixer@latest\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n
Next, run the following command to generate your tailwind.config.js<\/code> file.<\/p>\n
cd gatsby-theme-cloudinary-gallery\nnpx tailwindcss init \n<\/code><\/span><\/pre>\n
The last command will generate a tailwind.config.js<\/code> file in the gatsby-theme-cloudinary-gallery<\/code> directory. Update the tailwind.config.js<\/code> file like this.<\/p>\n
module<\/span>.exports = {\n  purge<\/span>: ['.\/src\/**\/*.{js,jsx,ts,tsx}'<\/span>],\n    darkMode<\/span>: false<\/span>, \/\/ or 'media' or 'class'<\/span>\n  theme<\/span>: {\n    extend<\/span>: {},\n  },\n  variants<\/span>: {\n    extend<\/span>: {},\n  },\n  plugins<\/span>: [],\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
Run the following command to create a global.css<\/code> file inside the gatsby-theme-cloudinary-gallery<\/code> directory under the src\/styles<\/code> folder.<\/p>\n
mkdir -p gatsby-theme-cloudinary-gallery\/src\/styles\ntouch gatsby-theme-cloudinary-gallery\/src\/styles\/global<\/span>.css\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n
Add the following code to the global.css<\/code> file.<\/p>\n
\/* gatsby-theme-cloudinary-gallery\/src\/styles\/global.css *\/<\/span>\n@tailwind<\/span> base;\n@tailwind<\/span> components;\n@tailwind<\/span> utilities;\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n
Create gatsby-browser.js<\/code> and gatsby-config.js<\/code> files in the gatsby-theme-cloudinary-gallery<\/code> directory by running the following command.<\/p>\n
touch gatsby-theme-cloudinary-gallery\/gatsby-browser.js\ntouch gatsby-theme-cloudinary-gallery\/gatsby-config.js\n<\/code><\/span><\/pre>\n
Add the following code to the gatsby-browser.js<\/code> file.<\/p>\n
import<\/span> '.\/src\/styles\/global.css'<\/span>;\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
Add the following code to the gatsby-config.js<\/code> file.<\/p>\n
module<\/span>.exports = {\n  siteMetadata<\/span>: {\n    title<\/span>: \"Gatsby Theme Cloudinary Gallery\"<\/span>,\n    description<\/span>:\n      \"Gatbsy Theme to add a Cloudinary Image Gallery to your Gatsby site.\"<\/span>,\n    social<\/span>: [\n      {\n        name<\/span>: \"GitHub\"<\/span>,\n        url<\/span>: \"https:\/\/github.com\/lelouchB\/gatsby-theme-cloudinary-gallery\"<\/span>,\n      },\n    ],\n  },\n  plugins<\/span>: [\n    {\n      resolve<\/span>: `gatsby-plugin-postcss`<\/span>,\n      options<\/span>: {\n        postCssPlugins<\/span>: [require<\/span>(\"tailwindcss\"<\/span>)],\n      },\n    },\n  ],\n};\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
You can refer to the official documentation for detailed instructions<\/a> on installing Tailwind CSS with Gatsby.<\/p>\n
How to create Heading Component<\/h2>\n
In this section, you will create the Heading<\/code> component that will show the following heading: Gatsby Theme Cloudinary Gallery<\/strong><\/em><\/p>\n
Run the following command to create a components<\/code> folder in the gatsby-theme-cloudinary-gallery\/src<\/code> directory.<\/p>\n
Inside the components<\/code> directory, create a file named Heading.js<\/code>.<\/p>\n
mkdir gatsby-theme-cloudinary-gallery\/src\/components\ntouch gatsby-theme-cloudinary-gallery\/src\/components\/Heading.js \n<\/code><\/span><\/pre>\n
Add the following code to the Heading.js<\/code> file.<\/p>\n
import<\/span> React from<\/span> \"react\"<\/span>;\n\nconst<\/span> Heading = ()<\/span> =><\/span> {\n  return<\/span> (\n    <h1<\/span> className<\/span>=\"text-4xl md:text-5xl text-center text-gray-800 font-sans font-medium\"<\/span>><\/span>\n      Gatsby Theme Cloudinary Gallery\n    <\/h1<\/span>><\/span><\/span>\n  );\n};\n\nexport<\/span> default<\/span> Heading;\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
The above code creates a simple heading styled with Tailwind CSS.<\/p>\n
The next step is to create a page to use this Heading<\/code> component. Run the following command to create a index.js<\/code> file in the src\/pages<\/code> sub-directory.<\/p>\n
mkdir gatsby-theme-cloudinary-gallery\/src\/pages\ntouch gatsby-theme-cloudinary-gallery\/src\/pages\/index.js \n<\/code><\/span><\/pre>\n
Add the following code to the pages\/index.js<\/code> file.<\/p>\n
import<\/span> React from<\/span> \"react\"<\/span>;\nimport<\/span> Heading from<\/span> \"..\/components\/Heading.js\"<\/span>;\n\nconst<\/span> Homepage = ()<\/span> =><\/span> {\n  return<\/span> (\n    <div<\/span> className<\/span>=\"bg-gray-200 min-h-screen p-8\"<\/span>><\/span>\n      <Heading<\/span> \/><\/span>\n    <\/div<\/span>><\/span><\/span>\n  );\n};\n\nexport<\/span> default<\/span> Homepage;\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
In the above code, you first import the Heading<\/code> component and then use it inside the Homepage<\/code> component.<\/p>\n
The last step is to create a gatsby-node.js<\/code> file that will create the page using Gatsby createPages<\/code> method and the pages\/index.js<\/code> file.<\/p>\n
Run the following command to create it.<\/p>\n
touch gatsby-theme-cloudinary-gallery\/gatsby-node.js\n<\/code><\/span><\/pre>\n
Add the following code to the gatsby-node.js<\/code> file.<\/p>\n
exports.createPages = async<\/span> ({ actions }, options) => {\n  const<\/span> basePath = options.basePath || \"\/\"<\/span>;\n\n  actions.createPage({\n    path<\/span>: basePath,\n    component<\/span>: require<\/span>.resolve(\".\/src\/pages\/index.js\"<\/span>),\n  });\n};\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
You export the createPages<\/code> method to create your page. You can read more about createPages<\/code> method here<\/a>.<\/p>\n
The above code creates a page dynamically at the \/<\/code> route. The options<\/code> object contains the props passed by the user when using the theme. You can read more about createPage<\/code> action here<\/a>.<\/p>\n
By default, the \/<\/code> route is used as the basePath<\/code>. If the user passes a value to the basePath<\/code> prop in the theme configuration, that value will be used instead.<\/p>\n
Start your development server by running the following command.<\/p>\n
yarn workspace gatsby-theme-cloudinary-gallery develop\n<\/code><\/span><\/pre>\n
Head over to http:\/\/localhost:8000\/<\/a> in your browser. Here is how your app will look like.<\/p>\n
\"Heading\"<\/p>\n
You can stop the development server by hitting CTRL+C<\/strong> in the terminal.<\/p>\n
You can also configure the demo<\/code> workspace to show the heading or the theme. Create a file named gatsby-config.js<\/code> in the demo<\/code> directory by running the following command.<\/p>\n
touch demo\/gatsby-config.js\n<\/code><\/span><\/pre>\n
Add the following code to gatsby-config.js<\/code>.<\/p>\n
\nmodule<\/span>.exports = {\n  plugins<\/span>: [\n    {\n      resolve<\/span>: \"gatsby-theme-cloudinary-gallery\"<\/span>,\n      options<\/span>: {\n        basePath<\/span>:\"\/gallery\"<\/span>,\n      },\n    },\n  ],\n};\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
Since you have passed \/gallery<\/code> to the basePath<\/code> prop, the theme or the heading will be displayed at the \/gallery<\/code> route.<\/p>\n
Start the development server for the demo workspace.<\/p>\n
yarn workspace demo develop\n<\/code><\/span><\/pre>\n
Head over to http:\/\/localhost:8000\/gallery<\/a>  in the browser. Here is how your app will look like.<\/p>\n
\"Heading\"<\/p>\n
How to create Gatsby Nodes from Images<\/h2>\n
In this section, you will fetch the images from Cloudinary and create Gatsby Nodes from them.<\/p>\n
Nodes<\/strong> are the center of Gatsby\u2019s data system. All the data that is added to Gatsby is modeled using nodes. You can read more about them here<\/a>.<\/p>\n
Nodes are created by calling the createNode<\/code> action. Nodes can be any object. Each Node has to be structured in a pre-defined manner<\/strong>, each with a unique id<\/strong>.<\/p>\n
In gatsby-node.js<\/code> file, create a function named createNodeData<\/code>. This function will convert image resources into node data.<\/p>\n
const<\/span> createNodeData = (gatsby, image, options<\/span>) =><\/span> {\n  return<\/span> {\n    id<\/span>: gatsby.createNodeId(`cloudinary-gallery-${image.public_id}<\/span>`<\/span>),\n    parent<\/span>: null<\/span>,\n    public_id<\/span>: image.public_id,\n    cloud_name<\/span>: options.cloudName,\n    internal<\/span>: {\n      type<\/span>: \"CloudinaryGallery\"<\/span>,\n      content<\/span>: JSON<\/span>.stringify(image),\n      contentDigest<\/span>: gatsby.createContentDigest(image),\n    },\n  };\n};\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
The createNodeData<\/code> function takes three arguments, gatsby<\/code>, image<\/code>, and the options<\/code> object. Here image<\/code> is the image resource fetched from Cloudinary.<\/p>\n
You are not creating a node in the above function, just structuring the data in the way needed to create the node.<\/em><\/p>\n
Each image resource has a public_id<\/code> which is passed in the public_id<\/code> key. The cloudName<\/code> is passed as a prop to the theme by the user. This cloudName<\/code> is accessed using the options<\/code> object, similar to the basePath<\/code> prop, and passed to the cloud_name<\/code> key.<\/p>\n
The parent<\/code> is a key reserved for plugins who wish to extend other nodes. It is not needed in this theme, so you pass null<\/code> to it.<\/p>\n
The type<\/code> is the globally unique node type. This will be used when running GraphQL queries.<\/p>\n
The contentDigest<\/code> is a short digital summary of the content of this node, and the content<\/code> exposes the raw content of this node that any transformation plugin can take and further process it.<\/p>\n
You can read more about Node Creation here<\/a>.<\/p>\n
Navigate to your Cloudinary dashboard in the browser and copy your Cloudinary Cloud Name<\/strong>, API Key<\/strong>, and API Secret<\/strong> from there.<\/p>\n
\"Cloudinary<\/p>\n
The next step is to create a function to fetch the images from Cloudinary and create nodes from them. You will use the cloudinary<\/code> npm package to do so.<\/p>\n
Run the following command to install cloudinary<\/code> and cloudinary-react<\/code>.<\/p>\n
yarn workspace gatsby-theme-cloudinary-gallery add cloudinary cloudinary-react\n<\/code><\/span><\/pre>\n
Import cloudinary<\/code> at the top of the gatsby-node.js<\/code> file.<\/p>\n
\/\/ gatsby-theme-cloudinary-gallery\/gatsby-node.js<\/span>\n\nconst<\/span> cloudinary = require<\/span>(\"cloudinary\"<\/span>).v2;\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
Create a function named createCloudinaryImageNodes<\/code> in the gatsby-node.js<\/code> file.<\/p>\n
const<\/span> createCloudinaryImageNodes = (gatsby, cloudinary, options<\/span>) =><\/span> {\n  const<\/span> cloudinaryOptions = {\n    type<\/span>: options.type || \"upload\"<\/span>,\n    max_results<\/span>: options.maxResults || 10<\/span>,\n    prefix<\/span>: options.prefix || ''<\/span>,\n  };\n\n  return<\/span> cloudinary.api.resources(cloudinaryOptions, (error, result) => {\n    result.resources.map((resource<\/span>) =><\/span> {\n      const<\/span> nodeData = createNodeData(gatsby, resource, options);\n      gatsby.actions.createNode(nodeData);\n    });\n  });\n};\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n
In the above code, the createCloudinaryImageNodes<\/code>  function takes gatsby<\/code>, cloudinary<\/code>, and options<\/code> as arguments.<\/p>\n
You create a cloudinaryOptions<\/code> object that contains the props to modify the Cloudinary fetch request. The user passes these props in the gatsby-config.js<\/code> file similar to the basePath<\/code> prop and is accessed using the options<\/code> object.<\/p>\n
These props are:<\/p>\n
The createNodeId<\/code> is a utility function to generate globally unique and stable node IDs. You can read more about the createNodeId<\/code> function here<\/a>.<\/p>\n