Gatsby is a React-based open-source framework for creating websites and apps. It allows developers to build fast, secure, and powerful web experiences using modern web technologies. Gatsby leverages GraphQL for data management and offers a rich plugin ecosystem to extend its functionality.
Static Site Generation
Gatsby can generate static pages from data sources like Markdown files. This code sample demonstrates how to create pages dynamically using GraphQL to query Markdown files and the createPage API to generate pages.
const path = require('path');
exports.createPages = async ({ graphql, actions }) => {
const { createPage } = actions;
const result = await graphql(`
{
allMarkdownRemark {
edges {
node {
frontmatter {
path
}
}
}
}
}
`);
result.data.allMarkdownRemark.edges.forEach(({ node }) => {
createPage({
path: node.frontmatter.path,
component: path.resolve(`src/templates/blog-post.js`),
context: {},
});
});
};GraphQL Data Layer
Gatsby uses GraphQL to manage data. This example shows how to query site metadata using GraphQL and display it in a React component.
import React from 'react';
import { graphql } from 'gatsby';
export const query = graphql`
query {
site {
siteMetadata {
title
}
}
}
`;
const IndexPage = ({ data }) => (
<div>
<h1>{data.site.siteMetadata.title}</h1>
</div>
);
export default IndexPage;Plugin Ecosystem
Gatsby has a rich plugin ecosystem that allows developers to extend its functionality. This example shows how to configure plugins for handling React Helmet, sourcing files from the filesystem, and transforming Markdown files.
module.exports = {
plugins: [
`gatsby-plugin-react-helmet`,
{
resolve: `gatsby-source-filesystem`,
options: {
name: `src`,
path: `${__dirname}/src/`,
},
},
`gatsby-transformer-remark`,
],
};Next.js is a React framework for server-side rendering and static site generation. It offers a more flexible approach to rendering, allowing developers to choose between static generation, server-side rendering, and client-side rendering on a per-page basis. Compared to Gatsby, Next.js is more versatile in terms of rendering options but may require more configuration for static site generation.
Nuxt.js is a framework for creating Vue.js applications with server-side rendering, static site generation, and client-side rendering. It provides a similar feature set to Gatsby but is built on Vue.js instead of React. Nuxt.js is ideal for developers who prefer Vue.js over React.
Gridsome is a Vue.js framework for building static websites and apps. It is similar to Gatsby in that it uses GraphQL for data management and offers a plugin ecosystem. Gridsome is a good alternative for developers who prefer Vue.js and want a static site generator with a similar feature set to Gatsby.
Transform plain text into dynamic blogs and websites using the latest web technologies. A React.js static site generator.
Build sites like it's 1995. Files are translated into HTML pages at the
same position within the file system. Add a markdown file at /docs/index.md and
it'll be converted to /docs/index.html.
Supports Markdown, HTML, and React.js components out of the box. Easy to add support for additional files types.
Leverages React Router's "nested component hierarchy" to make templating incredibly intuitive.
All templates, css, and content are hot reloadable.
If your site falls closer to the site end of the app<---->site spectrum then yes.
Gatsby is an excellent fit for blogs, marketing sites, docs sites, etc. Proper web apps should probably remain as normal web apps (though I'd love to be proved wrong!).
Gatsby is very new. APIs will break. Functionality is missing. It's usable but if you plan on building with it, expect a rocky road for some time.
Contributions welcome!
npm install -g gatsby
gatsby new my-test-gatsby-site This creates the
directory for your Gatsby project and adds the minimal files
needed.cd my-test-gatsby-sitegatsby develop — Gatsby will start a hot-reloading development
server accessible at localhost:8000The Gatsby cli tool lets you install "starters". These are partially built sites preconfigured to help you get moving faster on creating a certain type of site.
When creating a new site, you can optionally specify a starter to
base your new site on e.g. gatsby new [SITE_DIRECTORY] [URL_OF_STARTER]
For example, to quickly create a blog using Gatsby, you could install the Gatsby Starter Blog by running:
gatsby new blog https://github.com/gatsbyjs/gatsby-starter-blog
This downloads the files and initializes the site by running npm install
If you don't specify a custom starter, your site will created from the minimal default starter.
There are several starters that have been created. Create a PR to include yours!
npm install -g gatsbygatsby new docs-site gh:gatsbyjs/gatsby-starter-documentationcd docs-sitegatsby developconfig.toml.
Change the siteTitle key. The site's title should change shortly
after saving./pages/docs/getting-started/index.md and edit it. Again any saved
changes should load without refreshing in the browser.getting-started
directory to some-additional-steps. Then edit the markdown file
within the new directory. If you're familiar with other static site
generation software, you'll be familiar with the "frontmatter" at the
top of the file. Edit the title there + change the order to "5". Save
this. Ideally this new file would be hot reloaded like other changes
but I haven't figured out how to make this happen yet (help
appreciated here).
So to see your new page, restart gatsby develop and then refresh your
browser.gatsby build. The site is built to the /public
directory. Serve the site by going into the public directory and
typing python -m SimpleHTTPServerThe process is file --> Webpack loader --> React.js wrapper component --> static html page.
Gatsby leverages Webpack extensively. Webpack is a sophisticated module bundler that can turn any sort of file into a commonjs module. Webpack uses "Loaders" to convert a file into a module. These loaded modules are then wrapped inside a react.js component that's specific to a given file type. Gatsby then generates a static html page from this component.
Gatsby ships with default loaders and wrappers for HTML, Markdown, and JSX/CJSX but for most projects you'll want to write your own loaders and wrappers (very easy to do).
As an example of how this process works, let's walk quickly through converting a markdown file into an html page.
The default Gatsby markdown loader parses the markdown into HTML and uses Highlight.js to syntax highlight code blocks.
Our markdown file.
---
title: This is a title
---
# Hi friends.
This is a markdown file.
When loaded and required, the resulting javascript object looks like the following.
{
file: {
// Information about file on disk e.g. extension, directory path, etc.
},
data: {
title: "This is a title",
body: "<h1>Hi friends.</h1><p>This is a markdown file</p>"
}
}
Now Gatsby wraps the markdown file in this very simple React.js component.
module.exports = React.createClass({
displayName: "MarkdownWrapper",
render: function() {
post = @props.page.data
<div className="markdown">
<h1>{post.title}</h1>
<div dangerouslySetInnerHTML={{__html: post.body}}/>
</div>
}
})
Gatsby uses webpack-configurator to make changing the webpack loaders easy. The default set of loaders is organized by key.
Gatsby uses gatsby.config.js to pass control to the user before
resolving the final webpack configuration. gatsby.config.js should
live in the root of your project and export a function which accepts a
webpack-configurator config object and an environment string. The
environment string will be one of develop, static or
production.
Create a gatsby.config.js in the root of your project:
module.exports = function(config, env) {
// edit loaders here
return config;
}
Consider the following example which removes the default css loader and replaces it with a loader that uses css-modules.
module.exports = function(config, env) {
config.removeLoader('css');
config.loader('css', function(cfg) {
cfg.test = /\.css$/;
cfg.loader = 'style!css?modules'
return cfg
})
return config;
});
Each loader (cfg in the above example) can be a valid
webpack loader
and there are a host of
preexisting loaders
which you can use to enhance Gatsby.
It is also possible to write your own loaders.
Similar to the loaders, plugins are handled via
webpack-configurator
and gatsby.config.js.
If we wanted to extract all of the css in our project into a since
styles.css file for production, we could add the
ExtractTextWebpackPlugin. To do this, we need to modify the loader
and add the plugin when generating the static html for our site.
var ExtractTextPlugin = require("extract-text-webpack-plugin");
module.exports = function(config, env) {
if(env === 'static') {
config.removeLoader('css');
config.loader('css', function(cfg) {
cfg.test = /\.css$/;
cfg.loader = ExtractTextPlugin.extract('css?minimize');
return cfg
})
config.plugin('extract-css',
ExtractTextPlugin,
["styles.css", { allChunks: true }]);
}
}
Each plugin (extract-css in the above example) can be a valid
webpack plugin
and there are a host of
preexisting plugins
which you can use to enhance Gatsby.
It is also possible to write your own plugins.
/pages — All pages go here. Everything is turned into a page except
files which start with an underscore_template files — coming...Webpack doesn't currently support hot-reloading new files added to a context. When you add a new file, restart the gatsby develop process and your new page will show up.
Configuring babel-loader is as easy as creating a
.babelrc in the root of the
project. To enable stage 0 transforms, the following .babelrc could
be used:
{
"stage": 0
}
Gatsby supports automatically prefixing links with its link helper function.
To use simply import the function and run all links in your site thorough it e.g.
import { link } from 'gatsby-helpers'
link('/')
// During development this will return "/"
// When deployed to example.github.io/your-project/ this will return "/your-project/"
Set the prefix in your config file e.g. linkPrefix = '/your-project'
Then finally when building your site run gatsby build --prefix-links
The built site is now in /public. These files need copied to your
gh-pages branch and committed and pushed. You can do this manually or
use the handy gh-pages cli tool.
Both the sample sites are deployed to github pages and use link prefixing. Read their source for more help: documentation/blog.
FAQs
Blazing fast modern site generator for React
The npm package gatsby receives a total of 137,951 weekly downloads. As such, gatsby popularity was classified as popular.
We found that gatsby demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.