@reframejs/unframer 4.2.0-reframe.0

package/README.md

@@ -0,0 +1,389 @@
+<div hidden align='center'>
+    <br/>
+    <br/>
+    <h3>unframer</h3>
+    <p>design in Framer, deploy in React</p>
+    <br/>
+    <br/>
+</div>
+
+# @reframejs/unframer
+
+Reframe's maintained runtime for components exported from Framer. It is based on Unframer and is distributed with the Reframe CLI so generated components can keep their normal `unframer` imports.
+
+For installation and usage, see the [Reframe documentation](https://reframe.elxr.studio/docs).
+
+- Unframer exports your Framer components as simple .js files
+- Works with any React framework (Next.js, Remix, Vite, Astro, etc)
+- Includes all your components dependencies
+- Works with breakpoints, Framer fetch, Forms, color styles, dark mode (via `dark` class), etc
+- Full Typescript support, inferred from your component variables (like `variant`)
+
+## Usage
+
+You can watch a [Video Tutorial on YouTube here](https://www.youtube.com/watch?v=RL2BWqNSPhU) to see an overview of the process.
+
+1. Install unframer and update react to 19
+
+    ```sh
+    npm install unframer react@19 react-dom@19
+    ```
+
+1. Install the [`React Export` Framer plugin](https://framer.link/TGWRs2U), open it and select which components you want to export.
+
+1. Run the command `npx unframer {projectId} --outDir ./src/framer` to download the components and their types in the `outDir` directory.
+   Run this command every time you add a new Framer component.
+
+1. Import the components inside your `jsx` files together with `styles.css`, for example
+
+```tsx
+import './framer/styles.css' // load base Framer styles
+import Menu from './framer/menus'
+
+export default function App() {
+    return (
+        <div>
+            <Menu componentVariable='some variable' />
+        </div>
+    )
+}
+```
+
+1. To make sure everything works correctly install React 19 (latest version) and disable React Strict Mode in your app. Strict mode renders your components twice and this can cause issues with Framer animations.
+
+## Using responsive variants
+
+```tsx
+import './framer/styles.css'
+import Logos from './framer/logos'
+
+export default function App() {
+    return (
+        <div>
+            {/* Changes component variant based on breakpoint */}
+            <Logos.Responsive
+                // variants should be automatically generated by default by the Framer plugin, only pass them to override the defaults
+                variants={{
+                  lg: 'Your Desktop Variant',
+                  md: 'Your Tablet Variant',
+                  base: 'Your Mobile Variant',
+                }}
+            />
+        </div>
+    )
+}
+```
+
+## Styling
+
+You can use `className` or `style` props to style your components
+
+Notice that you will often need to use `!important` to override styles already defined in framer like `width` and `height`
+
+```tsx
+import './framer/styles.css'
+import Logos from './framer/logos'
+
+export default function App() {
+    return (
+        <div>
+            {/* Changes component variant based on breakpoint */}
+            <Logos.responsive
+                className='!w-full'
+                variants={{
+                    lg: 'Desktop',
+                    md: 'Tablet',
+                    base: 'Mobile',
+                }}
+            />
+        </div>
+    )
+}
+```
+
+## Sizing components
+
+Framer components can have a fixed size, this comes from the root element in the Framer component editor. To override this size you will need to use the `style` prop or use a class with high specificity.
+
+```tsx
+import './framer/styles.css'
+import Logos from './framer/logos'
+
+export default function App() {
+    return (
+        <div>
+            <Logos.responsive
+                className='!w-full' // use !important to override framer default size
+                style={{ width: '100%' }} // or use style prop, which has higher specificity than the Framer class
+                // variants are automatically generated by default by the Framer plugin, you only need to pass them to override them
+                variants={{
+                    lg: 'Desktop',
+                    md: 'Tablet',
+                    base: 'Mobile',
+                }}
+            />
+        </div>
+    )
+}
+```
+
+## Changing locale
+
+You can change locale of your component by passing `locale` prop to the component. The locale must be one of the country codes configured in your Framer project.
+
+```tsx
+import './framer/styles.css'
+import Logos from './framer/logos'
+
+export default function App() {
+    return (
+        <div>
+            <Logos locale='it-IT' />
+        </div>
+    )
+}
+```
+
+## Dark Mode
+
+Unframer supports dark mode through CSS classes:
+
+1. Add the `dark` class to any parent element of your component
+2. This will automatically switch all color style variables to use the dark mode values defined in Framer
+
+That's all you need to enable dark mode for your Framer components!
+
+> This is also how Tailwind's dark mode works - when you add the `dark` class to a parent element, any Tailwind dark mode classes (like `dark:bg-gray-900`) within that element will be activated. So you can seamlessly combine Framer and Tailwind dark mode by using the same `dark` class:
+
+```tsx
+import './framer/styles.css'
+import Logos from './framer/logos'
+
+export default function App() {
+    return (
+        <div className='dark'>
+            <Logos />
+        </div>
+    )
+}
+```
+
+## Using the Framer color styles as CSS variables
+
+Unframer will export your color styles as CSS variables, for example:
+
+> You can use Framer CSS variables in your own code, for example in tailwind with `<div className='bg-(--unframer-white)' />`
+
+```css
+:root {
+    --unframer-chambray: rgb(72, 86, 150);
+    --unframer-gray: rgb(231, 231, 231);
+    --unframer-off-black: rgb(16, 16, 16);
+    --unframer-300: rgb(255, 160, 122);
+    --unframer-500: rgb(252, 62, 19);
+    --unframer-dark-gray: rgb(169, 169, 169);
+    --unframer-400: rgb(254, 102, 57);
+    --unframer-100: rgb(255, 227, 212);
+    --unframer-50: rgb(255, 243, 237);
+    --unframer-25: rgb(255, 252, 250);
+    --unframer-white: rgb(255, 255, 255);
+    --unframer-primary: rgb(231, 34, 8);
+}
+
+.dark {
+    --unframer-chambray: rgb(161, 180, 255);
+    --unframer-gray: rgb(42, 42, 42);
+    --unframer-off-black: rgb(255, 255, 255);
+    --unframer-300: rgb(255, 160, 122);
+    --unframer-500: rgb(252, 62, 19);
+    --unframer-dark-gray: rgb(176, 176, 176);
+    --unframer-400: rgb(254, 102, 57);
+    --unframer-100: rgb(58, 58, 58);
+    --unframer-50: rgb(40, 40, 40);
+    --unframer-25: rgb(30, 30, 30);
+    --unframer-white: rgb(16, 16, 16);
+    --unframer-primary: rgb(231, 34, 8);
+}
+```
+
+## When should I run the plugin again?
+
+You can just run the `unframer` cli to get changes from the existing components.
+
+The Framer plugin should be reopened when:
+
+- When you add a new component
+- When changing color styles
+- When adding new pages (this is necessary to make relative links to those pages work)
+- When adding new locales
+- When changing breakpoints
+- When changing breakpoints
+
+## Watching for changes
+
+You can use the `--watch` flag to automatically re-export components when they change in Framer: notice that you will need to click the Publish button in Framer to trigger the cli, Framer only updates the JavaScript modules when you publish your website.
+
+<details>
+<summary>How it works</summary>
+Unframer cli will poll your website url every 2 seconds with a HEAD request, when the `etag` header changes it will re-export the components. This means that the --watch flag may not work if your components are not used in your main page of your Framer website.
+</details>
+
+## Using client navigation for links
+
+If you use a framework like Next.js or react-router you can pass a navigate function to let Unframer use client navigation instead of full page refreshes for relative links.
+
+All Unframer components below will use this navigate function to go to the new page.
+
+```tsx
+import { useRouter } from 'next/navigation'
+import { UnframerProvider } from 'unframer'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+    const router = useRouter()
+
+    return (
+        <UnframerProvider navigate={router.push}>{children}</UnframerProvider>
+    )
+}
+```
+
+## Passing locale prop to all components with `UnframerProvider`
+
+You can change the locale of all components under the provider passing locale prop to UnframerProvider.
+
+```tsx
+import { UnframerProvider } from 'unframer'
+
+export function Providers({ children }) {
+    return <UnframerProvider locale='de'>{children}</UnframerProvider>
+}
+```
+
+## How does unframer cli work?
+
+The Framer React Export plugin saves your Framer components JavaScript url in the Unframer database. When you run the Unframer cli the components urls are fetched and bundled with esbuild. The bundler will also resolve npm dependencies in your Framer overrides and code components using the latest version.
+
+You can customize the npm dependencies versions using the `--external` flag and installing them manually with `npm install`.
+
+Unframer will also create a `styles.css` file with the Framer global styles and the fonts used in your components.
+
+To generate TypeScript types for your components Unframer runs your downloaded components with Node.js and extracts the TypeScript types from the component `propertyControls` field, which is used to populate the Framer right bar controls.
+
+The Responsive component renders your components for each different breakpoint and only shows the current breakpoint via a CSS media query. The unused breakpoints are removed before hydration thanks to React [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore).
+
+## Troubleshooting
+
+If you find any errors rendering your components:
+
+- Check you have the latest version of `unframer` installed
+- If an animation is now working as expected try disabled React strict mode and updating to React 19.
+- Try downloading new versions of the components by running again `npx unframer {projectId}`, Framer may already have fixed the problem.
+- Try disabling React strict mode, this can cause many issues in Framer components.
+- If the export fails because Esbuild cannot find an export from a package (like `No matching export in "/:https://esm.sh/zustand" for import "default"`) you can use the `--external` option to externalie npm packages used by Framer, then install them manually with the right version with `npm install`.
+  Framer sometimes uses legacy versions of npm packages in their components, for example with Zustand which is usually still in version 3.x. This happens because Framer packages must be the same in the whole project and their versions are fixed at the time the npm package is used in a code component or override.
+
+## Supported component props
+
+`unframer` will add TypeScript definitions for your Framer components props and variables, some example variables you can use are:
+
+- `variant`, created when you use variants in Framer
+- functions, created when you use an `event` variable in Framer
+- Any scalar variable like String, Number, Boolean, Date, etc
+- Image variables (object with `src`, `srcSet` and `alt`), created when you use an `image` variable in Framer
+- Link strings, created when you make a link a variable in Framer
+- Rich text, created when you use a `richText` variable in Framer
+- Color, a string
+- React component, created when you use a `component` variable in Framer, for example in the Ticker component
+
+## Known limitations:
+
+- You may face React warnings like:
+    - `Accessing element.ref was removed in React 19.` This warning appears because Framer still uses the old `element.ref` API which was removed in React 19. This warning is harmless and will be fixed when Framer updates their codebase to use the new React 19 APIs.
+    - `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties.` This warning sometimes appears when using SVG icons, it should be harmless, it only happens in development mode.
+
+## Future Compatibility
+
+Every Framer runtime change is upstreamed automatically via Github Actions to this [file](https://github.com/remorses/unframer/blob/main/unframer/src/framer.js) and an example app is deployed [here](https://unframer-nextjs-app.vercel.app/). This means that if something breaks it's easy to bisect the specific change and fix it.
+
+For example in May 2024 Framer upgraded to React 19 and unframer broke, the reason was that framer runtime no longer injected ssr styles to `head` because react should do it automatically from version 19, this however broke unframer when using react 18, but i was able to quickly fix it by adding back the code to inject styles to `head` in unframer.
+
+## Performance
+
+Unframer renders your components with server side rendering, giving your good performance and SEO, in pair with the Framer deployed websites.
+
+Here is the below landing page Lighthouse score when using Astro:
+
+> **Important**: For best performance in development, disable React strict mode. Strict mode causes components to mount and unmount twice, which can cause issues with Framer animations and state management.
+
+![lighthouse score](https://raw.githubusercontent.com/remorses/unframer/main/assets/astro-performance.png)
+
+## Example
+
+Look at the [nextjs-app source code folder](https://github.com/remorses/unframer/tree/main/nextjs-app) for an example and [the deployed website here](https://unframer-nextjs-app.vercel.app/)
+
+## MCP CLI Commands
+
+Unframer can act as a command-line client for the [Framer MCP plugin](https://www.framer.com/marketplace/plugins/mcp/), allowing you to interact with your Framer project directly from the terminal.
+
+### Setup
+
+```sh
+# Login with your MCP URL (get it from the Framer MCP plugin)
+npx unframer mcp login
+```
+
+After login, all MCP commands become available. Run `npx unframer --help` to see the full list.
+
+### Example Commands
+
+```sh
+# Get project structure as XML
+npx unframer mcp getProjectXml
+
+# Get a specific node's XML by ID
+npx unframer mcp getNodeXml --nodeId "abc123"
+
+# Update node text or attributes
+npx unframer mcp updateXmlForNode --nodeId "abc123" --xml '<Text nodeId="abc123">New text</Text>'
+
+# Search for fonts
+npx unframer mcp searchFonts --query "Inter"
+
+# Export React components
+npx unframer mcp exportReactComponents
+
+# Get published website URL
+npx unframer mcp getProjectWebsiteUrl
+```
+
+### CMS Operations
+
+```sh
+# List all CMS collections
+npx unframer mcp getCMSCollections
+
+# Get items from a collection
+npx unframer mcp getCMSItems --collectionId "col123"
+
+# Create or update a CMS item
+npx unframer mcp upsertCMSItem --collectionId "col123" --slug "my-post" --fieldData '{"title": "Hello"}'
+```
+
+### Code Files
+
+```sh
+# Create a new code component
+npx unframer mcp createCodeFile --name "MyComponent.tsx" --content "export default function MyComponent() { return <div>Hello</div> }"
+
+# Read existing code file
+npx unframer mcp readCodeFile --codeFileId "code123"
+
+# Update code file content
+npx unframer mcp updateCodeFile --codeFileId "code123" --content "// updated code"
+```
+
+Run any command with `--help` for detailed options:
+
+```sh
+npx unframer mcp updateXmlForNode --help
+```

package/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { cli } from './dist/cli.js'
+
+cli.parse()

package/dist/babel-jsx.d.ts

@@ -0,0 +1,24 @@
+import type * as BabelTypes from '@babel/types';
+import type { PluginObj } from '@babel/core';
+export declare function removeJsxExpressionContainer({ types: t }: {
+    types: typeof BabelTypes;
+}): PluginObj;
+export declare function babelPluginJsxTransform({ types: t }: {
+    types: typeof BabelTypes;
+}): {
+    name: string;
+    visitor: {
+        ImportDeclaration(path: any): void;
+        CallExpression(path: any): void;
+    };
+};
+/**
+ * Injects `suppressHydrationWarning: true` into _jsx/_jsxs call props for elements
+ * that support it: lowercase HTML elements (div, span, etc.) and motion.* components.
+ * This prevents React hydration mismatch warnings caused by Framer's runtime rendering
+ * differently on server vs client (e.g. motion.div with layoutId, SVG containers, style attributes).
+ */
+export declare function babelPluginSuppressHydration({ types: t }: {
+    types: typeof BabelTypes;
+}): PluginObj;
+//# sourceMappingURL=babel-jsx.d.ts.map