Start

What is UXPin Merge?

UXPin Merge is the design-to-code infrastructure that connects UXPin with real React component libraries.

With Merge, you can import coded React components directly from your Git repository and use them inside the UXPin Editor. These components remain synchronized with the source code and behave exactly like the components used by developers in production.

This means designs built with Merge use the same components, properties, and logic as the real product.

What designers can do with Merge

• Use production React components directly inside the Editor
• Stop recreating UI elements that already exist in code
• Prototype complex behaviors using real component logic and data

What engineers can do with Merge

• Ensure designers work with the same components used in development
• Inspect JSX specifications generated from prototypes
• Extend prototypes with custom React components or integrations

What design systems teams can do with Merge

• Maintain a single source of truth for UI components in code
• Control component properties using PropTypes or TypeScript interfaces
• Manage design system versions through Git repositories

What leaders gain from Merge

• A shared workflow between design and engineering
• Faster iteration and reduced design-to-development handoff
• Prototypes that reflect real product behavior

How Merge works

Merge connects UXPin to your code repository and makes React components available inside the design editor. The process includes:

1. Analyzing the repository containing your component library
2. Building components using your project’s webpack configuration
3. Rendering those components inside UXPin as a design system library

Once connected, the same React components used in development can be used directly in design prototypes.

How Merge works with Forge

Merge and Forge are two core technologies of the UXPin platform.

Merge connects UXPin to real React component libraries.

Forge is UXPin’s AI engine that generates and edits UI using the components available in your project, including your Merge library when one is connected.

Instead of generic elements, Forge builds JSX from your exported React components and their props, so the generated UI follows the structure that exists in your codebase. To set it up, see Forge with React libraries.

How Merge works with Wire

Wire is UXPin’s AI-powered frontend app and design system builder. A new Wire project can start from a built-in component library (shadcn/ui, MUI, Ant Design or React Bootstrap), your Merge library, landing page template in HTML or a Design System MUI9 template.

To use your own library in Wire, connect it with Merge first. See Creating a Library. Push it to the same account or team where you use Wire. Merge has integration requirements, so test your components before you rely on them in Wire.

Wire uses Forge as its AI. If your library is already set up for Forge, Wire uses the same setup, so you don’t need to configure AI separately. See Forge with React libraries.

Wire and Merge connect in two ways:

• Build from your library. In the UXPin Editor, you can generate a Wire app from a component of your own Merge library.
• Publish to Merge. If you create a Design System in Wire you can publish it as Merge library. Use Publish as Merge library to compile and publish it, so its components are available in UXPin. Publishing requires Merge on your plan. The published library includes AI documentation that describes its components. For libraries built on the Custom library template, this is the MUI 9 documentation.

Check generated results against your design rules, because AI output isn’t guaranteed to follow every rule.

To learn more about building with Wire, see What is Wire.

To open Wire from the UXPin Editor, see Opening Wire.

What you need to get started

• A React component library in a Git repository
• Node.js 16 or later to run the Merge CLI
• webpack 4 or 5 and webpack-cli 4 or 5 installed in your project
• The Merge CLI, installed with npm install @uxpin/merge-cli --save-dev

React 16 to 18 are supported, and React 19 support is experimental.

Where to go next

• Start with a Boilerplate Repo: first steps, no deep JavaScript knowledge needed
• Integrating Your Own Components: advanced guide for your own library
• CLI Tool: commands and options
• AI-Assisted Merge Integration: connect your component library with Claude Code, from an npm package or from your own source code.

Examples of components

CSS Grid Implementation with Mineral UI Grid, Box and Card component

Video Background with Pinterest Gestalt Video component

Sortable Table that renders based on the provided data set

Bring your own design system

Merge works with React design systems, not only the ones listed below. You can bring yours in three ways:

• Integrate it with the Merge CLI. Best when you have a React component library in a Git repository and want full control. See Creating a Library.
• Integrate it with Claude Code. Best when your design system is an npm package, or React source code on your machine. Claude Code analyzes the library and creates component wrappers, properties, presets and tests. You review the result in the UXPin Editor. No previous Merge experience is required. See AI-Assisted Merge Integration.
• Create your own components in Wire. Best when you want to build components with AI. A Wire Design System project can be published as a Merge library, which makes its components available in UXPin. Publishing requires Merge on your plan.

Whichever route you choose, the result is the same: real React components, with the properties and behavior defined in code, inside the UXPin Editor. What you design uses the same components as production.

Can I use my own React design system in UXPin?

Yes. Merge imports React components from your Git repository. You can also use Claude Code to integrate an npm package or your source code.

Can AI create the Merge integration for me?

Yes, with the AI-assisted workflow in Claude Code. It creates the integration next to your design system and doesn’t modify your original source code. If a component can’t be integrated correctly, Claude Code skips it and reports it.

Which libraries are supported?

React component libraries. Web Components can be integrated through React wrappers. Vue and Angular components can’t currently be integrated.

Design systems tested with Merge

Merge has been tested with these design systems:

• CA Technologies Mineral UI
• Pivotal Labs Pivotal UI
• Atlassian Atlaskit
• Pinterest Gestalt
• Zendesk Garden
• Shopify Polaris
• IBM Carbon
• Instacart Snacks
• Material UI
• Microsoft Fluent UI
• RMWC
• Salesforce Lightning
• Semantic UI

Get access

Want access to UXPin Merge? Contact support at hello@uxpin.com.

Start with a Boilerplate Repo

The boilerplate repository is the fastest way to try UXPin Merge. In about 10 minutes, you run a sample design system in Merge experimental mode, play with its components in the UXPin Editor, and learn how to add a component of your own. The repository is here: uxpin-merge-boilerplate.

How long it takes: if Node.js is already installed on your computer and you know GitHub, 5 to 10 minutes. If you don’t have Node.js and haven’t used GitHub, reserve about an hour, most of it for installing the software.

What’s in the boilerplate

• Components: a configurable Button, Camera, CreditCard, Greeting, Icon, MediaPlayer, Select with nested SelectItem, Table that renders from data and adds sorting, TextField and TrendLine.
• Charts: five animated charts built with the React Vis library.

All components are built with React and styled with Emotion.

Before you start

• Node.js 16 or later and npm installed on your computer. If you don’t have them, download Node.js. npm comes with it.
• A GitHub account to fork the repository, and Git installed.
• A UXPin account.
• On Windows, you may need to run the commands in Windows Subsystem for Linux (WSL).

Run the boilerplate

1. Fork the boilerplate repository and clone it to your computer. If you’re new to Git and GitHub, see the GitHub guides, or contact support at hello@uxpin.com.
2. In the terminal, go to the root directory of the repository and install the dependencies, such as React, webpack and Babel:

npm install

3. Log in to your UXPin account at app.uxpin.com in your browser. You don’t need to open the UXPin app now. This is for authorization only, so stay logged in.

4. Start Merge experimental mode:

npm start

5. In a few seconds, experimental mode (the Merge Dev Environment) opens in your browser. Drag and drop components and play with their properties.

What you see in the browser

Experimental mode is a version of the UXPin Editor created for:

• testing how your components imported from code render, so you can check that everything is configured correctly,
• testing the properties of your components, so you can check that they work correctly.

This version of the Editor shouldn’t be used to design projects, and it isn’t everything Merge offers.

Add your own component

Once the boilerplate runs, you can add a component to your fork.

Prerequisites: you completed the steps above, you know HTML, CSS and JavaScript, and you have a basic understanding of React. The basic setup takes 5 to 10 minutes. The rest depends on your JavaScript skills and the components you want to add.

Merge reads uxpin.config.js in the root of the repository. It points to your webpack config and your wrapper, so npm start doesn’t need extra flags.

1. Make the directory, the filename and the component name identical, for example:

./src/components/NewComponent/NewComponent.jsx

2. Add a default export. A valid component looks like this:

import React from 'react';
import PropTypes from 'prop-types';

const NewComponent = (props) => <div>{props.children}</div>;

NewComponent.propTypes = {
  children: PropTypes.string,
};

export default NewComponent;

3. Define the props. PropTypes, Flow and TypeScript interfaces are supported. Props make a component editable in UXPin: Merge turns them into controls in the Editor’s Properties panel.

4. Create a JSX preset in the presets directory inside your component directory, for example:

./src/components/NewComponent/presets/0-default.jsx

import * as React from 'react';
import NewComponent from '../NewComponent';

export default (
  <NewComponent uxpId="newcomponent1">Hello World!</NewComponent>
);

See Authoring and Managing JSX Presets.

5. Add the component to uxpin.config.js:

categories: [
  {
    name: 'YourCategory',
    include: ['src/components/NewComponent/NewComponent.jsx'],
  },
],

See Config File.

6. Restart the process. Press Ctrl+C in the terminal, then run npm start again. If you get a lifecycle error, run killall -9 node and try again.

You should now see your component in the library in Merge.

Next steps

• Integrating Your Own Components to integrate your own React components
• AI-Assisted Merge Integration to connect your library with Claude Code
• Config File

Creating a Library

If you want to use your own React components in UXPin Merge, you’re in the right place. This page helps you choose how to start and shows the main steps from your repository to the UXPin Editor.

Choose how to start

• Start with a Boilerplate Repo: your first steps with Merge. Even if you’re not familiar with JavaScript, you can launch the dev environment and a sample design system.
• Integrating Your Own Components: an advanced tutorial on integrating your own components with Merge. Good if you already have experience with modern JavaScript.
• Storybook integration: for teams that already maintain their components in Storybook.
• AI-Assisted Merge Integration: connecting your component library with Claude Code, from an npm package or from your own source code. No previous Merge experience is required.

Before you start

• A React component library in a Git repository
• Node.js 16 or later
• webpack 4 or 5 and webpack-cli 4 or 5 installed in your project

The main steps

1. Install the Merge CLI in your project

npm install @uxpin/merge-cli --save-dev

2. Create the default config files

npx uxpin-merge init

It creates uxpin.config.js, uxpin.webpack.config.js, UXPinWrapper and an example Button component.

3. Create a library in the UXPin Editor and copy its token

Create a new library, select “Import React or Web Components from Git repo” and copy the authentication token. Don’t share it and don’t commit it to Git.

4. Push your library to UXPin

npx uxpin-merge push --token <your-library-token>

If you skip --token, the CLI reads the UXPIN_AUTH_TOKEN environment variable.

Optional: preview your components locally

Before you push, preview your components locally:

npx uxpin-merge

Running the tool without a command starts experimental mode.

Use your library in Forge and Wire

Once you’ve pushed your library, you can use it in UXPin:

• Forge: your library appears in the Library pill in Forge, and Forge can generate and edit UI with its components in the UXPin Editor. To give Forge your own rules, see Forge with React libraries.
• Wire: once the library is set up in Forge, you can generate a Wire app from a component of your own Merge library. Push the library to the same account or team first. See what you can build with Wire.

FAQ

What approaches to CSS are supported?

Merge is CSS agnostic. You can use pure CSS, Sass, Less, Styled Components, Emotion, and more. UXPin Merge renders a compiled version of your JS and CSS.

Can you use Web Components or Angular?

Right now Merge supports only React.js. Web Components are supported when they’re used through React wrappers. Vue and Angular components can’t currently be integrated directly with the AI-assisted workflow, but you may experiment with React wrappers for them. We’ve successfully integrated the RMWC design system, which consists of React.js wrappers for web components.

Which React versions work?

React 16 to 18 are supported. React 19 support is experimental.

AI-Assisted Merge Integration

Use Claude Code to integrate a React component library with UXPin Merge. Claude Code analyzes your library and creates everything Merge needs: component wrappers, properties, presets and tests. When it’s done, you review the components directly in the UXPin Editor. No previous Merge integration experience is required.

You can start from:

• an npm package, if your React component library is published on npm,
• your own source code, if your design system is a React repository on your computer.

What you need

• Node.js 18 or later
• Claude Code. If you don’t have it, run:

npm install -g @anthropic-ai/claude-code

• A UXPin account, with you logged in to UXPin in your browser. You’ll need it to preview the components later.
• Either an npm component library you want to integrate, or local access to your React design system repository

Step by step

Download the integration repository

Open the terminal and clone the UXPin Merge integration repository. It contains the instructions and configuration Claude Code uses to create and validate the integration.

git clone https://github.com/uxpin-merge/uxpin-merge-integration my-library-merge
cd my-library-merge

Start the integration

The start script checks your environment and opens Claude Code with the integration workflow ready to use.

For an npm package, on macOS or Linux run:

./start.sh

On Windows run:

start.cmd

For your own source code, pass the path to your design system when you start. On macOS or Linux run:

./start.sh /path/to/your/design-system

For example:

./start.sh ~/projects/company-design-system

On Windows run:

start.cmd C:\path\to\your\design-system

Passing the path at the start gives Claude Code access to the directory from the beginning, so it can read the components without unnecessary permission prompts.

Choose your component library

Claude Code analyzes your library and suggests a list of components to integrate. You can accept the list or ask Claude Code to add or remove components.

For an npm package, Claude Code asks where your library is. Enter the name of the npm package or a link, for example:

@company/design-system

It identifies the components, properties, dependencies and styling setup.

For your own source code, Claude Code reads the source and identifies the components, properties, TypeScript or JavaScript setup, styling, providers and dependencies.

Let Claude Code create the integration

After you confirm the component list, Claude Code first prepares a small number of components to check that the setup works, then continues with the rest in batches. Depending on your library, it creates:

• component wrappers (React wrappers for source code),
• properties available in the UXPin Properties panel,
• event handlers,
• presets,
• required providers,
• tests and validation.

The integration is validated as components are added, and you don’t need to create the Merge configuration manually for each component.

Preview the components in UXPin

During the integration, Claude Code starts UXPin Merge experimental mode and gives you its URL when the components are ready to review. Open the URL in your browser to see the local components inside the UXPin Editor. Make sure you’re logged in to UXPin. If your browser asks for permission to connect to a local server, allow it.

You can then:

• add components to the canvas,
• change their properties,
• try the available variants,
• check the presets,
• test the component behavior.

You can also start experimental mode manually with:

npx uxpin-merge

Review the integration

When the selected components are processed, Claude Code gives you a summary: the components that were integrated, the ones that were skipped and the reasons why (for source code), and the experimental mode URL.

If something doesn’t work as expected in UXPin, describe the issue to Claude Code, for example:

The Button size property does not update the component.

Claude Code updates the integration and runs the validation again. Repeat until the components work as expected.

Publish your library

When you’re happy with the integration, create a Merge library in UXPin and copy its Merge token:

• go to your UXPin account and open the UXPin Editor,
• create a new library,
• select the option “Import React or Web Components from Git repo”,
• copy the authentication token. Don’t share it with anyone, and don’t place it in any file checked into a Git repository. This token gives direct access to the library on your account.

Then run:

npx uxpin-merge push --token <your-merge-token>

The components are published to your UXPin Merge library and your team can use them in the Editor.

What happens to your library

Your original npm package or source code isn’t modified. The AI-assisted workflow creates a separate Merge integration based on the components and properties that actually exist in your library. UXPin-specific files go into a separate integration layer. Claude Code doesn’t invent properties or values that don’t exist. If a component can’t be integrated correctly, Claude Code skips it and reports it instead of adding a broken component.

Supported libraries

The AI-assisted workflow is intended for React component libraries. Web Components can be integrated through React wrappers created during the integration. Vue and Angular components can’t currently be integrated directly with this workflow.

After you push

Your library is available in the UXPin Editor. You can also use it with Forge, UXPin’s AI, to generate and edit UI with your components. See Forge with React libraries. For more about building apps with Wire, see What is Wire.

For more details about how the integration works, see the AI-assisted UXPin Merge integration guide.