Framer Projects

Framer projects are JavaScript projects. If you look inside one you'll find familiar files like package.json, node_modules, and yarn.lock. Folder-backed projects enable you to add your own external dependencies, whether private or public. They also make it possible to add Git for collaboration and leverage automation mechanisms. Along with our custom command line tool and Framer store, they allow you to keep your entire team in sync with the latest designs.

Folder Projects

Default Framer X projects are binary format with the .framerx extension. They are zip-compressed folders that get extracted temporarily while you work on them. This way we can optimize the experience for common users that like to double click to open, support multi-platform in the future, and make file sharing reliable.

For more advanced usage, like adding to Git, we also support folder-backed projects. They have the .framerfx extension and we set the bundle bit, so MacOS still sees them as a single file in the Finder that you can double click.

  • Create a new project, hold option and select File → Save. You’ll see a “File Format” option where you can select “Framer X (Folder).

  • For existing .framerx projects, change the extension in the Finder to .zip and double click to extract them. Rename the folder extension to .framerfx and it should get a Framer project icon.

External Libraries

Under the hood, Framer uses NPM with Yarn to manage all dependencies. You can easily install any external dependency like you would with other JavaScript projects.

Make sure you're using a folder-based project. Alternatively, you can open a .framerx file’s temporary location while the project is opened in Framer X by selecting File → Show Project Folder.

Use the terminal to navigate to your project location:

~ $ cd project.framerfx

Now you can install any NPM package using Yarn.

~/project.framerfx $ yarn add lodash @types/lodash

From here, the package will be added to the node_modules and package.json file. It will be available in all your code components and automatically installed as a dependency whenever a project gets opened.

Framer runs its own NPM registry, which is only used for packages in the @framer scope.

While most libraries work out of the box, some things might need tweaking in Framer. And because Framer runs the code, it may have performance or security implications for your projects (although the browser provides a fairly safe sandbox).

Private packages

To install packages from a private NPM registry, you can leverage your system-wide ~/.npmrc to set up the details of your registry.

As an example; let's assume the private registry is set up at https://registry.acme.corp and all packages are prefixed using the @acme scope. To set up the private registry, run the following commands in your terminal:

npm config set registry https://registry.acme.corp/ --scope=@acme
npm login --scope=@acme

After logging in, your private registry is set up and you will be able to install packages from your private registry:

~/project.framerfx $ yarn add @acme/library

Data from JSON

Framer X supports reading JSON data from any local file and use it directly in your code, so you can work with real data for any project.

  1. Open your project in Framer X and select File → Show Project Folder.

  2. Open the tsconfig.json file in your editor and add "resolveJsonModule": true to compilerOptions. See the documentation.

  3. You can now import any json document like you would any other module: import * as data from "./data.json"

As a bonus, VSCode will automatically pick up the contents of your json file and add it to type checking and autocomplete so you can avoid simple mistakes.

Git Integration

For Git integration, you'll need a folder-backed project. You can then simply add them to Git. When you open a project, Framer verifies if you have the right .gitignore rules in place and warns you if you don't.

Collaboration via Git on Framer project should go fairly well, as most files are mergeable. Try to avoid having multiple people edit json files like design/document.json as you'll have to merge them by hand. If you are planning to use many large media files, you might want to leverage Git LFS.


In addition to publishing packages through the core FramerX application, Framer also supports publishing folder packages from the command line through the framer-cli NPM package.

For use, leverage npx to run the framer-cli package:

npx framer-cli help


The framer-cli exposes four commands

  • authenticate

  • build

  • publish

  • help

The authenticate command provides a special FRAMER_TOKEN to be used as an environment variable for publishing packages under the authenticated user's account.

The build command ensures that the project is in a valid state for publishing.

The publish command is responsible for building the project, managing project versioning, and publishing the project to the correct store. This command requires a FRAMER_TOKEN environment variable for publishing. This token is unique to a given individual and is used for both authentication and determining the user's available private store, if any.

The help command prints the usage instructions and provides additional information about different options available for each function. Running a given command with the --help flag will also show information for that given command.

Automated Workflow

Because Framer projects can be set up as code repositories that use version management, they can also support multiple individuals making changes to the project at the same time.

When an individual’s changes get merged, an automated CI process can be kicked off to automatically publish a new version of the Framer package to the store using framer-cli.

This integration allows teams of developers and designers (or even a single individual) to work on the same Framer project and know that the store version of the package will always be up to date.


As an example of an automated publishing workflow, here is a small CircleCI configuration that uses the framer-cli module to publish a Framer package.

Note that this example assumes that the FRAMER_TOKEN environmental variable has already been set in the CI project settings.

# Javascript Node CircleCI 2.0 configuration file
# Check for more details
version: 2
- image: circleci/node:10
working_directory: ~/repo
- checkout
- run: yarn
- run: npx framer-cli publish --yes
version: 2
- publish:
only: master

Github Actions

It's also possible to use Github Actions to automate the release of a Framer package without the use of a separate CI. The Framer Bridge action can be added directly from the Marketplace, and an example of a build and publish workflow, ready to be cloned, can be found here.