@gravitywiz/gf-libraries-webpack-plugin

A Webpack plugin that aliases @gravityforms/libraries dependencies to control dependency versions and externalization.

What Does This Plugin Do?

When using @gravityforms/components from NPM, these components rely on @gravityforms/libraries as a centralized source for common dependencies like React, React Router, and other utilities.

For context, Gravity Forms chose this approach to decouple themselves from WordPress dependencies in case WordPress changes React versions or they want newer functionality. This makes sense, but adds friction for more simple use-cases.

This plugin:

1. Intercepts imports from @gravityforms/libraries and routes them to NPM packages in your project rather than the dependencies defined in @gravityforms/libraries.
2. Maintains webpack's tree-shaking capabilities - unused dependencies like React Router won't be included in your final bundle
3. Avoids duplicate React instances by using a single source
4. Makes dependencies work seamlessly with @wordpress/dependency-extraction-webpack-plugin. Most importantly, this makes Gravity Forms components use the same instance of React in your project (and more likely, the instance of React) provided by WordPress.

This approach allows Gravity Forms components to maintain a consistent dependency structure while giving you full control over dependency versions and bundle optimization.

Important Bundling Note

Since this plugin expects that you will use @wordpress/dependency-extraction-webpack-plugin, it will keep all Gravity Forms components and libraries as bundled modules, except for React and other core dependencies that are handled by WordPress.

How do I import Gravity Forms component styles?

You can enqueue the gform_admin_components registered stylesheet. Note, this will be for all components.

If you are using components that rely on simplebar, you will also need to enqueue gform_admin.

For more details, see Gravity Forms documentation.

How Does This Differ From @gravityforms/dependency-extraction-webpack-plugin?

@gravityforms/dependency-extraction-webpack-plugin acts similarly to @wordpress/dependency-extraction-webpack-plugin and will point packages such as components to externals made available to Gravity Forms. This works well, but falls apart when you want to share the same React instance with WordPress.

Since we're unable to transform these externals, this plugin should not be used with @gravityforms/dependency-extraction-webpack-plugin.

Installation

npm install --save-dev @gravitywiz/gf-libraries-webpack-plugin
# or
yarn add -D @gravitywiz/gf-libraries-webpack-plugin

Installing Peer Dependencies

This plugin requires several peer dependencies. You can install them all at once using:

npm install classnames@^2.5.1 immer@^10.1.1 prop-types@^15.8.1 rdndmb-html5-to-touch@^9.0.0 react@^18.0.0 react-calendar@^5.1.0 react-colorful@^5.6.1 react-dnd@^16.0.1 react-dnd-multi-backend@^9.0.0 react-dom@^18.0.0 react-file-drop@^3.1.6 react-paginate@^8.3.0 react-router-dom@^7.4.1 simplebar-react@^3.3.0 webpack@^5.0.0 zustand@^5.0.3

Or with yarn:

yarn add [...same packages and versions as npm command above]

Usage

const GFLibrariesPlugin = require('@gravitywiz/gf-libraries-webpack-plugin');
const DependencyExtractionWebpackPlugin = require('@wordpress/dependency-extraction-webpack-plugin');

module.exports = {
  // ... other webpack config
  module: {
    rules: [
      // Gravity Forms components are not transpiled by default (see https://docs.js.gravity.com/components-react/)
      {
        test: /\.js$/,
        exclude: [/node_modules\/(?!(@gravityforms)\/).*/],
        use: [
          {
            loader: 'babel-loader',
          },
        ],
      },
    ],
  },
  plugins: [
    new GFLibrariesPlugin(),
    new DependencyExtractionWebpackPlugin()
  ]
};

This webpack configuration ensures that:

1. Gravity Forms components are properly transpiled (they are not transpiled by default)
2. Dependencies are correctly aliased through this plugin
3. Core dependencies like React are externalized through WordPress

Configuration

You can optionally provide your own implementation of the libraries file:

new GFLibrariesPlugin({
  librariesPath: path.resolve(__dirname, './my-gf-libraries.js')
})

Example custom libraries file:

// my-gf-libraries.js
import React from 'react';
import * as ReactDOM from 'react-dom/client';
import PropTypes from 'prop-types';
import classnames from 'classnames';

// Only export the libraries you need
export {
    React,
    ReactDOM,
    PropTypes,
    classnames
};