larlet-fr-david-cache/cache/2024/d9c30865dde8c88394ba054836a18ae3/index.md

title: Designing a JavaScript Plugin System
url: https://css-tricks.com/designing-a-javascript-plugin-system/
hash_url: d9c30865dde8c88394ba054836a18ae3
archive_date: 2024-02-27
og_image: https://css-tricks.com/wp-json/social-image-generator/v1/image/318994
description: WordPress has plugins. jQuery has plugins. Gatsby, Eleventy, and Vue do, too.
favicon: https://css-tricks.com/favicon.svg
language: en_US

<p>WordPress has <a href="https://wordpress.org/plugins/" rel="noopener">plugins</a>. jQuery has <a href="https://plugins.jquery.com" rel="noopener">plugins</a>. <a href="https://www.gatsbyjs.org/docs/plugins/" rel="noopener">Gatsby</a>, <a href="https://www.11ty.dev/docs/plugins/" rel="noopener">Eleventy</a>, and <a href="https://css-tricks.com/getting-started-with-vue-plugins/">Vue </a>do, too.</p>



<p>Plugins are a common feature of libraries and frameworks, and for a good reason: they allow developers to add functionality, in a safe, scalable way. This makes the core project more valuable, and it builds a community — all without creating an additional maintenance burden. What a great deal!</p>



<p>So how do you go about building a plugin system? Let’s answer that question by building one of our own, in JavaScript.</p>



<span id="more-318994"></span>



<p class="explanation">I’m using the word “plugin” but these things are sometimes called other names, like “extensions,” “add-ons,” or “modules.” Whatever you call them, the concept (and benefit) is the same.</p>


<h3 class="wp-block-heading" id="lets-build-a-plugin-system"><a href="#aa-lets-build-a-plugin-system" aria-hidden="true" class="aal_anchor" id="aa-lets-build-a-plugin-system"><svg aria-hidden="true" class="aal_svg" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Let’s build a plugin system</h3>


<p>Let’s start with an example project called BetaCalc. The goal for BetaCalc is to be a minimalist JavaScript calculator that other developers can add “buttons” to. Here’s some basic code to get us started:</p>



<pre rel="JavaScript" class="wp-block-csstricks-code-block language-javascript" data-line=""><code markup="tt">// The Calculator
const betaCalc = {
  currentValue: 0,
  
  setValue(newValue) {
    this.currentValue = newValue;
    console.log(this.currentValue);
  },
  
  plus(addend) {
    this.setValue(this.currentValue + addend);
  },
  
  minus(subtrahend) {
    this.setValue(this.currentValue - subtrahend);
  }
};


// Using the calculator
betaCalc.setValue(3); // =&gt; 3
betaCalc.plus(3);     // =&gt; 6
betaCalc.minus(2);    // =&gt; 4</code></pre>



<p>We’re defining our calculator as an object-literal to keep things simple. The calculator works by printing its result via <code>console.log</code>.</p>



<p>Functionality is really limited right now. We have a <code>setValue</code> method, which takes a number and displays it on the “screen.” We also have <code>plus</code> and <code>minus</code> methods, which will perform an operation on the currently displayed value.</p>



<p>It’s time to add more functionality. Let’s start by creating a plugin system.</p>


<h3 class="wp-block-heading" id="the-worlds-smallest-plugin-system"><a href="#aa-the-worlds-smallest-plugin-system" aria-hidden="true" class="aal_anchor" id="aa-the-worlds-smallest-plugin-system"><svg aria-hidden="true" class="aal_svg" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The world’s smallest plugin system</h3>


<p>We’ll start by creating a <code>register</code> method that other developers can use to register a plugin with BetaCalc. The job of this method is simple: take the external plugin, grab its <code>exec</code> function, and attach it to our calculator as a new method:</p>



<pre rel="JavaScript" class="wp-block-csstricks-code-block language-javascript" data-line=""><code markup="tt">// The Calculator
const betaCalc = {
  // ...other calculator code up here


  register(plugin) {
    const { name, exec } = plugin;
    this[name] = exec;
  }
};</code></pre>



<p>And here’s an example plugin, which gives our calculator a “squared” button:</p>



<pre rel="JavaScript" class="wp-block-csstricks-code-block language-javascript" data-line=""><code markup="tt">// Define the plugin
const squaredPlugin = {
  name: 'squared',
  exec: function() {
    this.setValue(this.currentValue * this.currentValue)
  }
};


// Register the plugin
betaCalc.register(squaredPlugin);</code></pre>



<p>In many plugin systems, it’s common for plugins to have two parts:</p>



<ol><li>Code to be executed</li><li>Metadata (like a name, description, version number, dependencies, etc.)</li></ol>



<p>In our plugin, the <code>exec</code> function contains our code, and the <code>name</code> is our metadata. When the plugin is registered, the exec function is attached directly to our <code>betaCalc</code> object as a method, giving it access to BetaCalc’s <code>this</code>.</p>



<p>So now, BetaCalc has a new “squared” button, which can be called directly:</p>



<pre rel="JavaScript" class="wp-block-csstricks-code-block language-javascript" data-line=""><code markup="tt">betaCalc.setValue(3); // =&gt; 3
betaCalc.plus(2);     // =&gt; 5
betaCalc.squared();   // =&gt; 25
betaCalc.squared();   // =&gt; 625</code></pre>



<p>There’s a lot to like about this system. The plugin is a simple object-literal that can be passed into our function. This means that plugins can be downloaded via npm and imported as ES6 modules. Easy distribution is super important!</p>



<p>But our system has a few flaws.</p>



<p>By giving plugins access to BetaCalc’s <code>this</code>, they get read/write access to all of BetaCalc’s code. While this is useful for getting and setting the <code>currentValue</code>, it’s also dangerous. If a plugin was to redefine an internal function (like <code>setValue</code>), it could produce unexpected results for BetaCalc and other plugins. This violates <a href="https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle" rel="noopener">the open-closed principle</a>, which states that a software entity should be open for extension but closed for modification.</p>



<p>Also, the “squared” function works by producing <a href="https://en.wikipedia.org/wiki/Side_effect_(computer_science)" rel="nofollow noopener">side effects</a>. That’s not uncommon in JavaScript, but it doesn’t feel great — especially when other plugins could be in there messing with the same internal state. A more <a href="https://en.wikipedia.org/wiki/Functional_programming" rel="nofollow noopener">functional</a> approach would go a long way toward making our system safer and more predictable.</p>


<h3 class="wp-block-heading" id="a-better-plugin-architecture"><a href="#aa-a-better-plugin-architecture" aria-hidden="true" class="aal_anchor" id="aa-a-better-plugin-architecture"><svg aria-hidden="true" class="aal_svg" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>A better plugin architecture</h3>


<p>Let’s take another pass at a better plugin architecture. This next example changes both the calculator and its plugin API:</p>



<pre rel="JavaScript" class="wp-block-csstricks-code-block language-javascript" data-line=""><code markup="tt">// The Calculator
const betaCalc = {
  currentValue: 0,
  
  setValue(value) {
    this.currentValue = value;
    console.log(this.currentValue);
  },
 
  core: {
    'plus': (currentVal, addend) =&gt; currentVal + addend,
    'minus': (currentVal, subtrahend) =&gt; currentVal - subtrahend
  },


  plugins: {},    


  press(buttonName, newVal) {
    const func = this.core[buttonName] || this.plugins[buttonName];
    this.setValue(func(this.currentValue, newVal));
  },


  register(plugin) {
    const { name, exec } = plugin;
    this.plugins[name] = exec;
  }
};
  
// Our Plugin
const squaredPlugin = { 
  name: 'squared',
  exec: function(currentValue) {
    return currentValue * currentValue;
  }
};


betaCalc.register(squaredPlugin);


// Using the calculator
betaCalc.setValue(3);      // =&gt; 3
betaCalc.press('plus', 2); // =&gt; 5
betaCalc.press('squared'); // =&gt; 25
betaCalc.press('squared'); // =&gt; 625</code></pre>



<p>We’ve got a few notable changes here.</p>



<p>First, we’ve separated the plugins from “core” calculator methods (like <code>plus</code> and <code>minus</code>), by putting them in their own plugins object. Storing our plugins in a <code>plugin</code> object makes our system safer. Now plugins accessing this can’t see the BetaCalc properties — they can only see properties of <code>betaCalc.plugins</code>.</p>



<p>Second, we’ve implemented a <code>press</code> method, which looks up the button’s function by name and then calls it. Now when we call a plugin’s <code>exec</code> function, we pass it the current calculator value (<code>currentValue</code>), and we expect it to return the new calculator value.</p>



<p>Essentially, this new <code>press</code> method converts all of our calculator buttons into <a href="https://en.wikipedia.org/wiki/Pure_function" rel="nofollow noopener">pure functions</a>. They take a value, perform an operation, and return the result. This has a lot of benefits:</p>



<ul><li>It simplifies the API.</li><li>It makes testing easier (for both BetaCalc and the plugins themselves).</li><li>It reduces the dependencies of our system, making it more <a href="https://en.wikipedia.org/wiki/Loose_coupling" rel="noopener">loosely coupled</a>.</li></ul>



<p>This new architecture is more limited than the first example, but in a good way. We’ve essentially put up guardrails for plugin authors, restricting them to <a href="https://www.bryanbraun.com/2015/02/16/on-designing-great-systems/" rel="noopener">only the kind of changes that we want them to make</a>.</p>



<p>In fact, it might be too restrictive! Now our calculator plugins can only do operations on the <code>currentValue</code>. If a plugin author wanted to add advanced functionality like a “memory” button or a way to track history, they wouldn’t be able to.</p>



<p>Maybe that’s ok. The amount of power you give plugin authors is a delicate balance. Giving them too much power could impact the stability of your project. But giving them too little power makes it hard for them to solve their problems — in that case you might as well not have plugins.</p>


<h3 class="wp-block-heading" id="what-more-could-we-do"><a href="#aa-what-more-could-we-do" aria-hidden="true" class="aal_anchor" id="aa-what-more-could-we-do"><svg aria-hidden="true" class="aal_svg" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What more could we do?</h3>


<p>There’s a lot more we could do to improve our system.</p>



<p>We could add error handling to notify plugin authors if they forget to define a name or return a value. It’s good to think like a QA dev and imagine how our system could break so we can proactively handle those cases.</p>



<p>We could expand the scope of what a plugin can do. Currently, a BetaCalc plugin can add a button. But what if it could also register callbacks for certain lifecycle events — like when the calculator is about to display a value? Or what if there was a dedicated place for it to store a piece of state across multiple interactions? Would that open up some new use cases?</p>



<p>We could also expand plugin registration. What if a plugin could be registered with some initial settings? Could that make the plugins more flexible? What if a plugin author wanted to register a whole suite of buttons instead of a single one — like a “BetaCalc Statistics Pack”? What changes would be needed to support that?</p>


<h3 class="wp-block-heading" id="your-plugin-system"><a href="#aa-your-plugin-system" aria-hidden="true" class="aal_anchor" id="aa-your-plugin-system"><svg aria-hidden="true" class="aal_svg" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Your plugin system</h3>


<p>Both BetaCalc and its plugin system are deliberately simple. If your project is larger, then you’ll want to explore some other plugin architectures.</p>



<p>One good place to start is to look at existing projects for examples of successful plugin systems. For JavaScript, that could mean <a href="https://learn.jquery.com/plugins/basic-plugin-creation/" rel="nofollow noopener">jQuery</a>, <a href="https://www.gatsbyjs.org/docs/creating-plugins/" rel="nofollow noopener">Gatsby</a>, <a href="https://github.com/d3/d3/wiki/Plugins" rel="nofollow noopener">D3</a>, <a href="https://ckeditor.com/docs/ckeditor4/latest/guide/plugin_sdk_intro.html" rel="nofollow noopener">CKEditor</a>, or others.</p>



<p>You may also want to be familiar with various <a href="https://seesparkbox.com/foundry/javascript_design_patterns" rel="noopener">JavaScript design patterns</a>. (Addy Osmani <a href="https://addyosmani.com/resources/essentialjsdesignpatterns/book/" rel="noopener">has a book</a> on the subject.)  Each pattern provides a different interface and degree of coupling, which gives you a lot of good plugin architecture options to choose from. Being aware of these options helps you better balance the needs of everyone who uses your project.</p>



<p>Besides the patterns themselves, there’s a lot of good software development principles you can draw on to make these kinds of decisions. I’ve mentioned a few along the way (like the open-closed principle and loose coupling), but some other relevant ones include the <a href="http://wiki.c2.com/?LawOfDemeter" rel="nofollow noopener">Law of Demeter</a> and <a href="https://www.martinfowler.com/articles/injection.html" rel="noopener">dependency injection</a>.</p>



<p>I know it sounds like a lot, but you’ve gotta do your research. Nothing is more painful than making everyone rewrite their plugins because you needed to change the plugin architecture. It’s a quick way to lose trust and discourage people from contributing in the future.</p>


<h3 class="wp-block-heading" id="conclusion"><a href="#aa-conclusion" aria-hidden="true" class="aal_anchor" id="aa-conclusion"><svg aria-hidden="true" class="aal_svg" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h3>


<p>Writing a good plugin architecture from scratch is difficult! You have to balance a lot of considerations to build a system that meets everyone’s needs. Is it simple enough? Powerful enough? Will it work long term?</p>



<p>It’s worth the effort though. Having a good plugin system helps everyone. Developers get the freedom to solve their problems. End users get a large number of opt-in features to choose from. And you get to grow an ecosystem and community around your project. It’s a win-win-win situation.</p>