mirrorful-commit

Commit ™️

Edit directly in the browser.

Installation

The package is extremely small at ~40 kb.

npm i mirrorful-commit

Usage

Step 1

In _app.tsx:

import { MirrorfulPanel, MirrorfulProvider } from "mirrorful-commit";

export default function MyApp(..) {
  // Add this line
  const [isEditable, setIsEditable] = useState(false);

  // Rest of your existing code....

  // Add the MirrorfulProvider and the MirrorfulPanel. You want the Mirrorful panel to ONLY show in development/staging mode.
  return (
    <MirrorfulProvider>
      <Component {...pageProps} />
      {(process.env.NODE_ENV === "development" ||
        process.env.NODE_ENV === "staging") && (
        <MirrorfulPanel
          isEditable={isEditable}
          setIsEditable={setIsEditable}
          githubClientId={process.env.GITHUB_CLIENT_ID ?? ""}
          repo={"repo you are currently in"}
          owner={"owner of github repo you are currently in"}
          prettierConfig={{
            // NOTE: Copy paste your prettier config from your repo so the formatting matches
            tabWidth: 2,
            singleQuote: true,
            semi: false,
            trailingComma: "es5",
          }}
        />
      )}
    </MirrorfulProvider>
  );
}

Step 2

You need to add a callback page for the redirect URI for Github Oauth. The route should be: ${document.location.origin}/mirrorful/callback. In other words, if using Next.js, the route is: pages/mirrorful/callback/index.tsx and the content should be:

import { MirrorfulCallbackPage } from "mirrorful-commit";

export default MirrorfulCallbackPage;

Step 3

Step 3.1

Create a file called mirrorful-plugin.js wherever your next.config.js is located (probably in root).

As a shortcut, run this whenever your next.config.js is located.

touch mirrorful-plugin.js; touch babel.config.js

The content should be:

module.exports = function (babel) {
  const { types: t } = babel;

  return {
    name: "add-data-attribute-plugin",
    visitor: {
      JSXOpeningElement(path, state) {
        const filePath = state.file.opts.filename;

        // Check if the JSX element already has a data-mirrorful attribute
        const existingAttr = path.node.attributes.find((attr) =>
          t.isJSXIdentifier(attr.name, { name: "data-mirrorful" })
        );

        // If it doesn't, then add the attribute
        if (!existingAttr) {
          const dataAttr = t.jsxAttribute(
            t.jsxIdentifier("data-mirrorful"),
            t.stringLiteral(filePath)
          );
          path.node.attributes.push(dataAttr);
        }
      },
    },
  };
};

All this does is add a data attribute to all DOM nodes.

Step 3.2

Finally, add a babel.config.js in the same location (probably in root) that uses the plugin we created above. The content should be:

// NOTE: Use whatever env you have to indicate it's not production. While the plugin is "harmless" and fast, you probably don't want a data attribute on every DOM node in production.
const isDevelopment = process.env.NODE_ENV !== "production";
console.log("Running Mirrorful?", isDevelopment, "env", process.env.NODE_ENV);
module.exports = {
  presets: ["next/babel"],
  plugins: isDevelopment ? ["./mirrorful-plugin.js"] : [],
};

Step 4

That's it. You're done. There is no step 4. 🎉

Troubleshooting ⚙️

Duplicate identifier error

When building:

Failed to compile.

./blabalba.tsx:95:16
Syntax error: Identifier 'Foobar' has already been declared.

If you see this, it's because it seems next/babel is slightly different than SWC. Ultimately, it means you do have a duplicate identifier in ./blabalba.tsx and you should fix it.