Gatsby Plugin for No-JavaScript Static Sites

0.13.2 · active · verified Sun Apr 19

gatsby-plugin-no-javascript-utils is a Gatsby plugin designed to assist in generating purely static sites with minimal to no client-side JavaScript. It currently ships as version 0.13.2, which supports Gatsby versions 2 through 5, indicating a stable but relatively slow release cadence, typical for plugins that modify core build outputs rather than introduce new features. Its primary differentiator is its focus on stripping out various JavaScript-related artifacts that Gatsby typically includes by default, such as script tags, preload links for scripts and page data, JavaScript sourcemaps, and client-side routing announcers. Additionally, it offers options to remove generator meta tags, data attributes from head elements (like `data-react-helmet`), and convert inline `<style data-href>` tags to external `<link>` tags for improved caching and smaller HTML files. This makes it ideal for highly SEO-sensitive sites or those targeting extremely lightweight builds where JavaScript is entirely optional or handled externally.

Common errors

```
My Gatsby site isn't interactive; client-side routing and components don't work.
```
cause The `noScript` option is enabled, which removes all JavaScript from the site.

fix If you need client-side interactivity, set `noScript: false` in the plugin options, or remove `gatsby-plugin-no-javascript-utils` entirely if JavaScript is fundamental to your site's functionality.
```
My styles are missing or incorrect after enabling `noInlineStyles: true`.
```
cause The build process might not be correctly generating or linking external CSS files, or some styles were expected to be inlined and are now missing.

fix Inspect your `public` directory to ensure CSS files are being generated. Check the browser's network tab to see if CSS `<link>` tags are loading the correct files. Adjust your Gatsby styling setup if necessary to ensure compatibility with external CSS linking.
```
I'm seeing a Gatsby generator meta tag even though I tried to remove it.
```
cause The `gatsby-plugin-no-javascript-utils` plugin is likely not the last plugin in your `gatsby-config.js` plugins array.

fix Move `gatsby-plugin-no-javascript-utils` to the very end of your `plugins` array in `gatsby-config.js`.

Warnings

breaking Enabling `noScript: true` (which is the default) will remove all client-side JavaScript, including Gatsby's hydration, routing, and any interactive components. This will effectively render your Gatsby site as a purely static HTML site.
Fix: Ensure your site is intended to be purely static with no client-side interactions if `noScript` is enabled. Test thoroughly to confirm no essential functionality relies on JavaScript.
gotcha This plugin must be included last in your `gatsby-config.js` plugins array. If placed earlier, other plugins might re-introduce scripts or modify output in ways that conflict with this plugin's clean-up process.
Fix: Always place `'gatsby-plugin-no-javascript-utils'` as the final entry in your `plugins` array in `gatsby-config.js`.
gotcha Using `noInlineStyles: true` converts `<style data-href>` tags to `<link>` tags. While beneficial for caching, it requires the corresponding CSS files to be served correctly by your build/deployment process. This might conflict with certain CSS-in-JS solutions or build setups that expect styles to be inlined.
Fix: Verify that your build pipeline correctly generates and serves external CSS files when `noInlineStyles` is active. Test your site's styling thoroughly across browsers.
gotcha Disabling `removeGatsbyAnnouncer` (default: false) might leave the accessibility announcer div in your HTML, which is primarily useful for client-side route changes. If `noScript` is enabled, this element becomes largely redundant and adds unnecessary markup.
Fix: If `noScript` is enabled, it's recommended to set `removeGatsbyAnnouncer: true` to further reduce HTML bloat and ensure consistency with a pure static site approach.

Install

npm install gatsby-plugin-no-javascript-utils npm
yarn add gatsby-plugin-no-javascript-utils yarn
pnpm add gatsby-plugin-no-javascript-utils pnpm

Imports

gatsby-plugin-no-javascript-utils
wrong:
```
import { GatsbyPluginNoJavascriptUtils } from 'gatsby-plugin-no-javascript-utils';
```
correct:
```
// In gatsby-config.js
module.exports = {
  plugins: [
    // ... other plugins
    'gatsby-plugin-no-javascript-utils',
  ],
};
```
This package is a Gatsby plugin and is configured via `gatsby-config.js`. It does not export symbols for direct import into component or utility files. Its inclusion is typically last in the plugin array.

Config with options

wrong:

require('gatsby-plugin-no-javascript-utils').configure({ noScript: true });

correct:

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-no-javascript-utils',
      options: {
        noScript: true,
        noSourcemaps: false,
        removeGeneratorTag: true
      },
    },
  ],
};

Plugin options are passed via the standard Gatsby plugin configuration object structure in `gatsby-config.js`. Direct programmatic configuration is not supported.

Quickstart

This quickstart demonstrates how to add the plugin to `gatsby-config.js` and configure its main options to achieve a truly JavaScript-free Gatsby build, optimizing for minimal HTML output and enhanced caching.

// In your gatsby-config.js
module.exports = {
  siteMetadata: {
    title: 'My Static Blog',
    description: 'A website with no JavaScript.',
  },
  polyfill: false, // Often disabled when removing JS
  plugins: [
    // Ensure this plugin is placed last to guarantee all scripts are removed
    // and other modifications are applied after other plugins have run.
    {
      resolve: 'gatsby-plugin-no-javascript-utils',
      options: {
        noScript: true, // Default: true - Removes all scripts and preload links
        noSourcemaps: true, // Default: true - Disables JS sourcemap generation
        removeGeneratorTag: true, // Default: true - Removes Gatsby generator meta tag
        removeHeadDataAttrs: true, // Default: true - Removes data-react-helmet and data-gatsby-head attrs
        noInlineStyles: true, // Default: false - Replaces <style data-href> with <link> tags
        removeGatsbyAnnouncer: true // Default: false - Removes accessibility announcer div
      }
    },
  ],
};

view raw JSON →