DOCSEARCHbyAlgolia
Submit Docs

MightyMeld Documentation

website·Indexed 32 days ago

https://docs.mightymeld.com

Documentation for MightyMeld, featuring guides on setup, CLI usage, and integration plugins for frameworks like Next.js, Remix, Vite, and Create React App. Includes details on the 'scribe' code processing system, prefabs, views, and configuration via mightymeld.json.

Tokens
7.2K
Snippets
43
Records
71
Agent score
47%

What's inside MightyMeld

  1. Use Views for design experimentation and component development

    Views in MightyMeld provide a dedicated space to build and iterate outside the primary structure of your application. They are primarily used to:

    • Experiment with new design ideas without modifying the live app.
    • Isolate components to test them in different states.
    • Create and maintain a design system gallery.
    • Build new components or edit existing ones in isolation.

  2. Understand the purpose of the MightyMeld plugin

    The MightyMeld plugin (available for Babel and SWC) instruments code with source locations (file name, line number, etc.). This allows MightyMeld to map rendered browser elements back to their original source code. Most frameworks provide this information natively, so the plugin is only required if you can see your app in the MightyMeld studio but cannot select elements.

  3. Install MightyMeld SWC plugin for Next.js 13.4.19 and above

    For Next.js versions 13.4.19 and above, use the SWC plugin. First, install the plugin using the version tag that matches your Next.js version (next-13, next-14.1, or next-14.2). Then, configure next.config.js to enable the plugin when the MIGHTYMELD environment variable is present.
    # Replace VERSION with next-13, next-14.1, or next-14.2
npm install --save-dev @mightymeld/swc-plugin@VERSION
    /** @type {import('next').NextConfig} */
const nextConfig = {};

if (process.env.MIGHTYMELD) {
  const { options } = require('@mightymeld/swc-plugin/options');
  nextConfig.experimental = {
    swcPlugins: [['@mightymeld/swc-plugin', options()]]
  };
}

module.exports = nextConfig;

  4. Integrate MightyMeld plugin into a CRACO-based React app

    For applications created with Create React App that already use CRACO, the MightyMeld plugin can be integrated by installing the mightymeld package and adding a conditional Babel plugin to the CRACO configuration. This ensures the plugin is only active when the application is being run by MightyMeld (detected via the MIGHTYMELD environment variable).
    npm install --save-dev mightymeld
    // craco.config.js
module.exports = {
    webpack: {
        ...
    }
};

// Use MightyMeld plugin when run by MightyMeld.
if (process.env.MIGHTYMELD) {
    module.exports.babel = {
        plugins: ["mightymeld/babel-plugin-mightymeld"]
    };
}

  5. Fix element selection issues in Next.js

    MightyMeld requires accurate source locations to map rendered JSX elements back to code. If elements cannot be selected in Next.js:

    1. React Server Components (RSC): Server-rendered components lack source location data. Install the MightyMeld plugin to add reliable source locations.
    2. SWC Versioning: If using Next.js with SWC on a version lower than 14.0.2, upgrade to 14.0.2 or higher to fix a bug where source locations are missing (fixed in SWC 1.3.96). This does not affect apps using Babel (e.g., those with a .babelrc file).
    3. Include/Exclude Settings: Ensure the target elements are in files covered by the include setting in your configuration.

  6. Upgrade MightyMeld CLI from version 0.1.x

    Starting with version 0.2.0, the package name changed from @mightymeld/runtime to mightymeld. Users upgrading from 0.1.x must uninstall the old package. Additionally, if using CRA or Vite 5+, the Babel or SWC plugin is no longer required and should be removed from .babelrc or vite.config.js.
    npm uninstall @mightymeld/runtime

  7. Install MightyMeld Babel plugin for Next.js 13.4.18 and below

    For Next.js versions 13.4.18 and below, use the Babel plugin. Note that this is incompatible with the @next/font package; if you use @next/font, upgrade Next.js to use the SWC plugin instead. You must install both the mightymeld runtime and @babel/types. Create a babel.config.js file and ensure the next/babel preset is included to maintain Next.js functionality.
    npm install --save-dev mightymeld @babel/types
    // Base config needed by Next.js
const babel = {
  presets: ['next/babel']
};

if (process.env.MIGHTYMELD) {
  babel.plugins = ['mightymeld/babel-plugin-mightymeld'];
}

module.exports = babel;

  8. Configure MightyMeld for Vite using @vitejs/plugin-react-swc

    To use MightyMeld with Vite and SWC, you must use @vitejs/plugin-react-swc version 3.1.0 or above. This setup is experimental and is specifically for users of the SWC-based React plugin; those using @vitejs/plugin-react should use the Babel-based instructions instead. The plugin is conditionally added to the Vite configuration only when the MIGHTYMELD environment variable is present.
    npm install --save-dev @mightymeld/swc-plugin
    import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import { options } from '@mightymeld/swc-plugin/options';

const plugins = [];
if (process.env.MIGHTYMELD) {
  plugins.push(['@mightymeld/swc-plugin', options()]);
}

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react({
      plugins
    })
  ]
});

  10. Add and configure prefabs in a MightyMeld project

    To add prefabs to your project, create a dedicated directory (e.g., src/prefabs) and register it in the mightymeld.json configuration file using the prefab_dir key. Ensure the directory is included in the project's include paths and not explicitly excluded. After adding JSX or TSX prefab files to the directory and committing them to git, restart the MightyMeld process (npx mightymeld) and reload the studio in the browser to see the prefabs in the library panel.
    {
    "include": ...,
    "run": ...,
    "prefab_dir": "src/prefabs"
}

  11. Install and initialize MightyMeld in a React project

    To get started with MightyMeld, navigate to the directory containing your React app's package.json and install the CLI. You can install it globally or as a development dependency. After installation, run the mightymeld command via npx to launch an interactive setup wizard that creates a mightymeld.json configuration file and starts the MightyMeld studio. Subsequent runs will skip the setup process.
    # Option 1: Global installation
npm install -g mightymeld

# Option 2: Local development dependency
npm i -D mightymeld

# Initialize and start MightyMeld studio
npx mightymeld

  12. Implement the MightyMeld View Box in a React application

    The View Box is a marker used by MightyMeld to determine where to inject view components. Use the {/* @mightymeld-viewbox */} comment to designate the injection point.

    Behavioral rules:

    • Components placed above the View Box are always rendered.
    • Components placed below (or inside) the View Box are replaced by the view content when a view is displayed.
    • To ensure views have access to React context or themes, wrap the View Box and its children within the necessary providers.
    import App from './App';
import { ThemeProvider } from './theme';

// ThemeProvider is outside the View Box, so views can use it
<ThemeProvider>
  {/* @mightymeld-viewbox */}
  <App /> {/* App is inside the View Box, so it will be replaced by view content */}
</ThemeProvider>;