{"data":{"prismicDocsCategory":{"data":{"pages":[{"page":{"uid":"merge-start","document":[{"data":{"title":{"text":"Start"},"visible_in_table_of_content":"true"}}]}},{"page":{"uid":"merge-connect-your-library","document":[{"data":{"title":{"text":"Connect your library"},"visible_in_table_of_content":"true"}}]}},{"page":{"uid":"for-developers","document":[{"data":{"title":{"text":"For Developers"},"visible_in_table_of_content":"true"}}]}},{"page":{"uid":"merge-use-in-the-editor","document":[{"data":{"title":{"text":"Use in the Editor"},"visible_in_table_of_content":"true"}}]}},{"page":{"uid":"merge-publish-and-maintain","document":[{"data":{"title":{"text":"Publish and maintain"},"visible_in_table_of_content":"true"}}]}},{"page":{"uid":"merge-faq","document":[{"data":{"title":{"text":"Frequently Asked Questions"},"visible_in_table_of_content":"true"}}]}}]}},"prismicDocsPage":{"data":{"title":{"text":"Publish and maintain"},"isVisibleForRobots":"true","body":[{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":"CLI Tool"},"content":{"html":"

The UXPin Merge CLI analyzes your component repository, prepares your code for UXPin, lets you test components locally in experimental mode, and pushes them to your UXPin account.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Install

The CLI requires Node.js 16 or later, and webpack 4 or 5 with webpack-cli 4 or 5 in your project.

"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"npm install @uxpin/merge-cli --save-dev"}]},"language":"JavaScript"}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

or

"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"yarn add @uxpin/merge-cli --dev"}]},"language":"JavaScript"}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Quick start

  1. npx uxpin-merge init: creates the default config files
  2. npx uxpin-merge: starts experimental mode so you can test components
  3. npx uxpin-merge summary: shows what the CLI found without building it
  4. npx uxpin-merge push --token <token>: uploads your library to UXPin
"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Commands

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Options

Global options

Options for push

Options for other commands

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Environment

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":"Connecting code to UXPin (CI & push)"},"content":{"html":"

To bring your React components into UXPin, you push them with the Merge CLI. The recommended way is to push automatically from a continuous integration (CI) server, such as CircleCI or GitHub Actions (any CI server that can run Node.js works), so the library in UXPin always matches your code. You can also push once by hand.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Before you start

Create a library in UXPin and copy its authentication token:

  1. Go to your UXPin account and open the UXPin Editor.
  2. Click the library name in the bottom left corner, then click New library.
  3. Select the option “Import React or Web Components from Git repo”.
  4. Name the library and click Create library.
  5. Copy the authentication token. Don’t share it with anyone, and don’t place it in any file checked into your Git repository. This token gives direct access to the library on your account.
"}}},{"__typename":"PrismicDocsPageBodyVideo","slice_type":"video","primary":{"video_link":{"url":"https://uxpincommunity.cdn.prismic.io/uxpincommunity/bbf00279-79fe-495c-8ad4-993ed73668d9_Connecting+code+to+UXPin+CI+push.mp4"},"video_description":{"text":null}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Set up your CI server

Once you have the token, go to your CI app and start a project that tracks your design system repository, if you haven’t yet. Then:

  1. Add an environment variable UXPIN_AUTH_TOKEN with the value set to your token.
  2. In your CI config, add a step that runs:
"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"npx uxpin-merge push"}]},"language":"JavaScript"}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Two things to check in your CI setup:

For more options, such as tagging a push with --tag, see CLI Tool and Merge library version control.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

CircleCI

  1. Create a CircleCI config file: ./.circleci/config.yml.
  2. Copy this YAML into it:
"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"version: 2.1\n\njobs:\n build:\n docker:\n - image: cimg/node:18.20\n working_directory: ~/project/\n steps:\n - checkout\n - run:\n name: Install dependencies\n command: npm install\n - run:\n name: Push to UXPin\n command: npx uxpin-merge push\n\nworkflows:\n push-to-uxpin:\n jobs:\n - build"}]},"language":"JavaScript"}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

3. Open CircleCI and add a new project.

4. Search for your GitHub repository and click Set Up Project. If the project already has a config file, click “Use Existing Config”.

5. Click Start Building. The first sync will start and fail, because the token isn’t set yet.

6. Go to Project Settings > Environment Variables.

7. Add a new environment variable: name UXPIN_AUTH_TOKEN, value: the token you copied from UXPin.

8. Rerun the integration.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

GitHub Actions

  1. Create a GitHub Actions workflow file: ./.github/workflows/uxpin-merge.yml.
  2. Copy this YAML into it:
"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"name: Deploy-uxpin\n\non: push\n\njobs:\n deploy-uxpin:\n name: UXPin update\n runs-on: ubuntu-latest\n if: \"github.ref == 'refs/heads/master' && !contains(github.event.head_commit.message, 'skip ci')\"\n steps:\n - uses: actions/checkout@v4\n with:\n ref: refs/heads/master\n fetch-depth: 0\n - name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n - name: Install\n run: yarn\n - name: Push to UXPin\n run: yarn push\n env:\n UXPIN_AUTH_TOKEN: ${{ secrets.UXPIN_AUTH_TOKEN }}"}]},"language":"JavaScript"}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

3. Make sure the scripts section of package.json has "push": "uxpin-merge push".

4. In GitHub, open your repository, click the Settings tab, then Secrets.

5. Add a new repository secret: name UXPIN_AUTH_TOKEN, value: the token you copied from UXPin.

6. Push a change to master. This starts the GitHub Actions sync.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

A one-time push

An alternative to a CI server is a one-time push. Use it only if you don’t plan frequent updates of your components. In your terminal, run:

"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"npx uxpin-merge push --token "}]},"language":"JavaScript"}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Don’t save your token in any file checked into the repository.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Next steps

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":"Version Control"},"content":{"html":"

When you manage a design system that’s continuously updated alongside the product, you can run into different design system versions in different prototypes. Ideally you keep your library up to date as much as possible, but you may also want to control when to upgrade the design system version.

Merge version control gives you the flexibility to manage the library version for each project. You can freely switch between the versions you’ve added.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Branch or Tag

In Merge, you choose the library version for a given prototype in one of two ways, a branch or a version tag.

Branch

Tag

"}}},{"__typename":"PrismicDocsPageBodyTip","slice_type":"tip","primary":{"tip_type":"Info tip mini size","tip_title":"NOTE","tip":{"html":"

You can push a tag only once. You can’t push your library to UXPin again with the same tag, so you have to specify a new tag each time.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Always use the latest version

If you always want to use the latest version of your design system, select the checkbox to follow “Latest”. A prototype then updates automatically whenever the library changes, because it always references the latest version of the branch.

"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Add a version to your library

To add a tag version, use the --tag option when you push from the CLI:

"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"npx uxpin-merge push --token --tag "}]},"language":null}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

To push a working branch, use the --branch option:

"}}},{"__typename":"PrismicDocsPageBodyCode","slice_type":"code","primary":{"code":{"raw":[{"text":"npx uxpin-merge push --token --branch "}]},"language":null}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Delete a version

To delete a tag or a branch from your library, use delete-version:

npx uxpin-merge delete-version --token <your-library-token> --tag <version>\nnpx uxpin-merge delete-version --token <your-library-token> --branch <branch>
"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Switch the version for a prototype

"}}},{"__typename":"PrismicDocsPageBodyVideo","slice_type":"video","primary":{"video_link":{"url":"https://uxpincommunity.cdn.prismic.io/uxpincommunity/b1cc8568-05e9-47f9-baed-7e86b8939647_01_manage.mp4"},"video_description":{"text":"How to switch a version for a prototype"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"
  1. Click the gear icon while you open the Merge library you want to control.
  2. Click “Manage Version in project” in the library panel.
  3. Choose the version you want to use for the prototype.
"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"

Set a default version for future prototypes

"}}},{"__typename":"PrismicDocsPageBodyVideo","slice_type":"video","primary":{"video_link":{"url":"https://uxpincommunity.cdn.prismic.io/uxpincommunity/30e52ad2-6aeb-43b0-9dfd-8612f8ca1514_02_library.mp4"},"video_description":{"text":"How to set a default version for future prototypes"}}},{"__typename":"PrismicDocsPageBodyContent","slice_type":"content","primary":{"content_title":{"text":null},"content":{"html":"
  1. Click the gear icon while you open the Merge library you want to control.
  2. Click “Library settings” in the library panel.
  3. Choose the version you want to use for future prototypes.
"}}}]}}},"pageContext":{"isCreatedByStatefulCreatePages":false,"categoryUid":"merge","pageUid":"merge-publish-and-maintain","meta_description":"UXPin's merge Docs, publish and maintain for new and advanced users","meta_image":"https://images.prismic.io/uxpincommunity/fa3875f8df8606e6405ba46165becc1ea6ed3d34.png?auto=compress,format","meta_title":"Publish and maintain | Merge","page_title":"Publish and maintain | Merge"}}