@figma-vars/hooks 2.0.0-beta.1 → 2.0.0-beta.2

package/README.md

@@ -26,6 +26,8 @@ Built for the modern web, this library provides a suite of hooks to fetch, manag
 - **✍️ Ergonomic Mutations**: A `useMutation`-style API for creating, updating, and deleting variables, providing clear loading and error states.
 - **🔒 TypeScript-first**: Strictly typed for an ergonomic and safe developer experience. Get autocompletion for all API responses.
 - **📖 Storybook & Next.js Ready**: Perfect for building live design token dashboards or style guides.
+- **🔄 Local JSON Support**: Use local JSON files exported from Figma Dev Mode plugins when you don't have a Figma Enterprise account, enabling offline development and static deployments.
+- **🚧 Style Dictionary Integration**: Coming soon in future beta releases - seamless integration with Amazon's Style Dictionary for multi-platform design token distribution.
 
 ---
 
@@ -162,6 +164,61 @@ function CreateVariableForm({ collectionId }: { collectionId: string }) {
 }
 ```
 
+### Using Local JSON Files (No Enterprise Account Required)
+
+If you don't have a Figma Enterprise account (required for the Variables API), you can still use this library with local JSON files exported from Figma Dev Mode plugins. This is perfect for:
+
+- **Offline Development**: Work on your design system without an internet connection
+- **Static Deployments**: Deploy design token dashboards to static hosting
+- **CI/CD Pipelines**: Use exported JSON files in automated workflows
+- **Team Collaboration**: Share design tokens without API access
+
+#### Getting Your JSON File
+
+We recommend using the [Variables Exporter for Dev Mode](https://www.figma.com/community/plugin/1491572182178544621) plugin:
+
+1. Install the plugin in Figma
+2. Open your Figma file in Dev Mode
+3. Run the plugin and export your variables as JSON
+4. Save the JSON file to your project (e.g., `src/assets/figma-variables.json`)
+
+This plugin exports the exact same format that the Figma Variables API returns, ensuring perfect compatibility with this library.
+
+#### Using the Fallback File
+
+```tsx
+// src/main.tsx or App.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { FigmaVarsProvider } from '@figma-vars/hooks'
+import App from './App'
+import variablesData from './assets/figma-variables.json'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <FigmaVarsProvider
+      token={null} // No token needed when using fallbackFile
+      fileKey="your-figma-file-key"
+      fallbackFile={variablesData}>
+      <App />
+    </FigmaVarsProvider>
+  </React.StrictMode>
+)
+```
+
+You can also pass the JSON as a string if you prefer:
+
+```tsx
+import variablesJson from './assets/figma-variables.json?raw'
+
+<FigmaVarsProvider
+  token={null}
+  fileKey="your-figma-file-key"
+  fallbackFile={variablesJson}>
+  <App />
+</FigmaVarsProvider>
+```
+
 ### Figma PAT Security
 
 When using the Figma API, it's essential to keep your Personal Access Token (PAT) secure. Here are some best practices:
@@ -231,11 +288,19 @@ function ErrorHandling() {
 
 ### Core Hooks
 
-- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns a SWR hook state with `data`, `isLoading`, and `error` properties. The actual Figma response is in `data.data`.
+- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns a SWR hook state with `data`, `isLoading`, and `error` properties. The actual Figma response is in `data.data`. When `fallbackFile` is provided, it uses the local JSON data instead of making an API request.
 - `useVariableCollections()`: A convenience hook that returns just the variable collections from the main `useVariables` data.
 - `useVariableModes()`: A convenience hook that returns just the variable modes from the main `useVariables` data.
 - `useFigmaToken()`: A simple hook to access the token and file key from the context.
 
+### Provider Props
+
+The `FigmaVarsProvider` accepts the following props:
+
+- `token`: Figma Personal Access Token (PAT) for API authentication. Can be `null` when using `fallbackFile`.
+- `fileKey`: Figma file key for the target file. Required for API requests but can be any string when using `fallbackFile`.
+- `fallbackFile`: Optional local JSON file (as object or string) to use instead of API requests. Perfect for users without Figma Enterprise accounts.
+
 ### Mutation Hooks
 
 All mutation hooks return an object with the following shape: `{ mutate, data, isLoading, error }`.

package/dist/hooks/useVariables.d.ts

@@ -4,7 +4,9 @@ import { LocalVariablesResponse } from '../types/figma';
  *
  * @remarks
  * This hook uses SWR for caching and revalidation. It fetches the variables for the
- * file key provided via the FigmaVarsProvider context.
+ * file key provided via the FigmaVarsProvider context. If a fallbackFile is provided,
+ * it will use that instead of making an API request, which is useful for users without
+ * Figma Enterprise accounts or for offline development.
  *
  * @returns SWR response object with `data`, `error`, `isLoading`, and `isValidating`.
  *

package/dist/hooks/useVariables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariables.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0LAUxB,CAAC"}
+{"version":3,"file":"useVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariables.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,0LAoBxB,CAAC"}

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("react/jsx-runtime"),i=require("react"),_=require("swr"),p=i.createContext(void 0),v=({children:e,token:o,fileKey:t,fallbackFile:r})=>{const s=r===void 0?{token:o,fileKey:t}:{token:o,fileKey:t,fallbackFile:r};return b.jsx(p.Provider,{value:s,children:e})},l=()=>{const e=i.useContext(p);if(e===void 0)throw new Error("useFigmaTokenContext must be used within a FigmaVarsProvider");return e},h="https://api.figma.com",w=`${h}/v1/variables`,T=w,A=e=>`${w}/${e}`,I="application/json",y="X-FIGMA-TOKEN",c="A Figma API token is required.",g="An error occurred while fetching data from the Figma API.";async function V(e,o){if(!o)throw new Error(c);const t=await fetch(e,{method:"GET",headers:{[y]:o,"Content-Type":I}});if(!t.ok){let r=g;try{const s=await t.json();s!=null&&s.message&&(r=s.message)}catch{}throw new Error(r)}return t.json()}const E=()=>{const{token:e,fileKey:o}=l(),t=e&&o?`https://api.figma.com/v1/files/${o}/variables/local`:null;return _(t&&e?[t,e]:null,t&&e?([s,n])=>V(s,n):()=>Promise.resolve(void 0))},R=()=>{const{data:e}=E(),o=i.useMemo(()=>e!=null&&e.meta?Object.values(e.meta.variableCollections):[],[e]),t=i.useMemo(()=>e!=null&&e.meta?e.meta.variableCollections:{},[e]);return{collections:o,collectionsById:t}},C=()=>{const{data:e}=E();return i.useMemo(()=>{const o=[],t={},r={};if(e!=null&&e.meta)for(const s of Object.values(e.meta.variableCollections)){o.push(...s.modes),t[s.id]=s.modes;for(const n of s.modes)r[n.modeId]=n}return{modes:o,modesByCollectionId:t,modesById:r}},[e])};function M(e,o){switch(o.type){case"loading":return{...e,status:"loading",error:null};case"success":return{...e,status:"success",data:o.payload};case"error":return{...e,status:"error",error:o.payload};default:return e}}const d=e=>{const o={status:"idle",data:null,error:null},[t,r]=i.useReducer(M,o);return{mutate:i.useCallback(async n=>{r({type:"loading"});try{const a=await e(n);return r({type:"success",payload:a}),a}catch(a){r({type:"error",payload:a});return}},[e]),...t,isLoading:t.status==="loading",isSuccess:t.status==="success",isError:t.status==="error"}};async function m(e,o,t,r){if(!o)throw new Error(c);const a={method:{CREATE:"POST",UPDATE:"PUT",DELETE:"DELETE"}[t],headers:{"Content-Type":"application/json",[y]:o}};r&&(a.body=JSON.stringify(r));const u=await fetch(`${h}${e}`,a);if(!u.ok){const f=await u.json().catch(()=>({}));throw new Error(f.err||f.message||"An API error occurred")}return u.status===204||!u.body?{}:u.json()}const P=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(c);return await m(T,e,"CREATE",t)})},O=()=>{const{token:e}=l();return d(async({variableId:t,payload:r})=>{if(!e)throw new Error(c);return await m(A(t),e,"UPDATE",r)})},D=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(c);return await m(A(t),e,"DELETE",void 0)})},F=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(c);return await m(T,e,"CREATE",t)})};function S(e,o){return e.filter(t=>{let r=!0;return o.resolvedType&&(r=r&&t.resolvedType===o.resolvedType),o.name&&(r=r&&t.name.includes(o.name)),r})}exports.FigmaVarsProvider=v;exports.filterVariables=S;exports.useBulkUpdateVariables=F;exports.useCreateVariable=P;exports.useDeleteVariable=D;exports.useUpdateVariable=O;exports.useVariableCollections=R;exports.useVariableModes=C;exports.useVariables=E;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("react/jsx-runtime"),i=require("react"),_=require("swr"),p=i.createContext(void 0),g=({children:e,token:r,fileKey:t,fallbackFile:o})=>{const s=o===void 0?{token:r,fileKey:t}:{token:r,fileKey:t,fallbackFile:o};return b.jsx(p.Provider,{value:s,children:e})},l=()=>{const e=i.useContext(p);if(e===void 0)throw new Error("useFigmaTokenContext must be used within a FigmaVarsProvider");return e},h="https://api.figma.com",w=`${h}/v1/variables`,T=w,y=e=>`${w}/${e}`,v="application/json",A="X-FIGMA-TOKEN",u="A Figma API token is required.",I="An error occurred while fetching data from the Figma API.";async function V(e,r){if(!r)throw new Error(u);const t=await fetch(e,{method:"GET",headers:{[A]:r,"Content-Type":v}});if(!t.ok){let o=I;try{const s=await t.json();s!=null&&s.message&&(o=s.message)}catch{}throw new Error(o)}return t.json()}const E=()=>{const{token:e,fileKey:r,fallbackFile:t}=l(),o=async(n,a)=>t?typeof t=="string"?JSON.parse(t):t:V(n,a),s=e&&r?`https://api.figma.com/v1/files/${r}/variables/local`:null;return _(s&&e?[s,e]:null,s&&e?([n,a])=>o(n,a):()=>Promise.resolve(void 0))},R=()=>{const{data:e}=E(),r=i.useMemo(()=>e!=null&&e.meta?Object.values(e.meta.variableCollections):[],[e]),t=i.useMemo(()=>e!=null&&e.meta?e.meta.variableCollections:{},[e]);return{collections:r,collectionsById:t}},C=()=>{const{data:e}=E();return i.useMemo(()=>{const r=[],t={},o={};if(e!=null&&e.meta)for(const s of Object.values(e.meta.variableCollections)){r.push(...s.modes),t[s.id]=s.modes;for(const c of s.modes)o[c.modeId]=c}return{modes:r,modesByCollectionId:t,modesById:o}},[e])};function M(e,r){switch(r.type){case"loading":return{...e,status:"loading",error:null};case"success":return{...e,status:"success",data:r.payload};case"error":return{...e,status:"error",error:r.payload};default:return e}}const d=e=>{const r={status:"idle",data:null,error:null},[t,o]=i.useReducer(M,r);return{mutate:i.useCallback(async c=>{o({type:"loading"});try{const n=await e(c);return o({type:"success",payload:n}),n}catch(n){o({type:"error",payload:n});return}},[e]),...t,isLoading:t.status==="loading",isSuccess:t.status==="success",isError:t.status==="error"}};async function m(e,r,t,o){if(!r)throw new Error(u);const n={method:{CREATE:"POST",UPDATE:"PUT",DELETE:"DELETE"}[t],headers:{"Content-Type":"application/json",[A]:r}};o&&(n.body=JSON.stringify(o));const a=await fetch(`${h}${e}`,n);if(!a.ok){const f=await a.json().catch(()=>({}));throw new Error(f.err||f.message||"An API error occurred")}return a.status===204||!a.body?{}:a.json()}const P=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(u);return await m(T,e,"CREATE",t)})},F=()=>{const{token:e}=l();return d(async({variableId:t,payload:o})=>{if(!e)throw new Error(u);return await m(y(t),e,"UPDATE",o)})},O=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(u);return await m(y(t),e,"DELETE",void 0)})},S=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(u);return await m(T,e,"CREATE",t)})};function D(e,r){return e.filter(t=>{let o=!0;return r.resolvedType&&(o=o&&t.resolvedType===r.resolvedType),r.name&&(o=o&&t.name.includes(r.name)),o})}exports.FigmaVarsProvider=g;exports.filterVariables=D;exports.useBulkUpdateVariables=S;exports.useCreateVariable=P;exports.useDeleteVariable=O;exports.useUpdateVariable=F;exports.useVariableCollections=R;exports.useVariableModes=C;exports.useVariables=E;

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { jsx as _ } from "react/jsx-runtime";
-import { createContext as I, useContext as v, useMemo as d, useReducer as R, useCallback as g } from "react";
+import { createContext as I, useContext as v, useMemo as d, useReducer as g, useCallback as R } from "react";
 import C from "swr";
-const f = I(void 0), N = ({
+const f = I(void 0), S = ({
   children: t,
   token: o,
   fileKey: e,
@@ -14,10 +14,10 @@ const f = I(void 0), N = ({
   if (t === void 0)
     throw new Error("useFigmaTokenContext must be used within a FigmaVarsProvider");
   return t;
-}, p = "https://api.figma.com", h = `${p}/v1/variables`, w = h, A = (t) => `${h}/${t}`, b = "application/json", T = "X-FIGMA-TOKEN", c = "A Figma API token is required.", P = "An error occurred while fetching data from the Figma API.";
-async function M(t, o) {
+}, p = "https://api.figma.com", h = `${p}/v1/variables`, w = h, A = (t) => `${h}/${t}`, b = "application/json", T = "X-FIGMA-TOKEN", i = "A Figma API token is required.", P = "An error occurred while fetching data from the Figma API.";
+async function F(t, o) {
   if (!o)
-    throw new Error(c);
+    throw new Error(i);
   const e = await fetch(t, {
     method: "GET",
     headers: {
@@ -37,12 +37,12 @@ async function M(t, o) {
   return e.json();
 }
 const y = () => {
-  const { token: t, fileKey: o } = u(), e = t && o ? `https://api.figma.com/v1/files/${o}/variables/local` : null;
+  const { token: t, fileKey: o, fallbackFile: e } = u(), r = async (n, a) => e ? typeof e == "string" ? JSON.parse(e) : e : F(n, a), s = t && o ? `https://api.figma.com/v1/files/${o}/variables/local` : null;
   return C(
-    e && t ? [e, t] : null,
-    e && t ? ([s, n]) => M(s, n) : () => Promise.resolve(void 0)
+    s && t ? [s, t] : null,
+    s && t ? ([n, a]) => r(n, a) : () => Promise.resolve(void 0)
   );
-}, S = () => {
+}, V = () => {
   const { data: t } = y(), o = d(
     () => t != null && t.meta ? Object.values(t.meta.variableCollections) : [],
     [t]
@@ -54,15 +54,15 @@ const y = () => {
     collections: o,
     collectionsById: e
   };
-}, B = () => {
+}, k = () => {
   const { data: t } = y();
   return d(() => {
     const o = [], e = {}, r = {};
     if (t != null && t.meta)
       for (const s of Object.values(t.meta.variableCollections)) {
         o.push(...s.modes), e[s.id] = s.modes;
-        for (const n of s.modes)
-          r[n.modeId] = n;
+        for (const c of s.modes)
+          r[c.modeId] = c;
       }
     return {
       modes: o,
@@ -88,16 +88,16 @@ const l = (t) => {
     status: "idle",
     data: null,
     error: null
-  }, [e, r] = R(O, o);
+  }, [e, r] = g(O, o);
   return {
-    mutate: g(
-      async (n) => {
+    mutate: R(
+      async (c) => {
         r({ type: "loading" });
         try {
-          const a = await t(n);
-          return r({ type: "success", payload: a }), a;
-        } catch (a) {
-          r({ type: "error", payload: a });
+          const n = await t(c);
+          return r({ type: "success", payload: n }), n;
+        } catch (n) {
+          r({ type: "error", payload: n });
           return;
         }
       },
@@ -111,8 +111,8 @@ const l = (t) => {
 };
 async function m(t, o, e, r) {
   if (!o)
-    throw new Error(c);
-  const a = {
+    throw new Error(i);
+  const n = {
     method: {
       CREATE: "POST",
       UPDATE: "PUT",
@@ -123,19 +123,19 @@ async function m(t, o, e, r) {
       [T]: o
     }
   };
-  r && (a.body = JSON.stringify(r));
-  const i = await fetch(`${p}${t}`, a);
-  if (!i.ok) {
-    const E = await i.json().catch(() => ({}));
+  r && (n.body = JSON.stringify(r));
+  const a = await fetch(`${p}${t}`, n);
+  if (!a.ok) {
+    const E = await a.json().catch(() => ({}));
     throw new Error(E.err || E.message || "An API error occurred");
   }
-  return i.status === 204 || !i.body ? {} : i.json();
+  return a.status === 204 || !a.body ? {} : a.json();
 }
-const G = () => {
+const B = () => {
   const { token: t } = u();
   return l(async (e) => {
     if (!t)
-      throw new Error(c);
+      throw new Error(i);
     return await m(
       w,
       t,
@@ -143,12 +143,12 @@ const G = () => {
       e
     );
   });
-}, j = () => {
+}, G = () => {
   const { token: t } = u();
   return l(
     async ({ variableId: e, payload: r }) => {
       if (!t)
-        throw new Error(c);
+        throw new Error(i);
       return await m(
         A(e),
         t,
@@ -157,11 +157,11 @@ const G = () => {
       );
     }
   );
-}, k = () => {
+}, j = () => {
   const { token: t } = u();
   return l(async (e) => {
     if (!t)
-      throw new Error(c);
+      throw new Error(i);
     return await m(
       A(e),
       t,
@@ -173,7 +173,7 @@ const G = () => {
   const { token: t } = u();
   return l(async (e) => {
     if (!t)
-      throw new Error(c);
+      throw new Error(i);
     return await m(
       w,
       t,
@@ -189,13 +189,13 @@ function x(t, o) {
   });
 }
 export {
-  N as FigmaVarsProvider,
+  S as FigmaVarsProvider,
   x as filterVariables,
   L as useBulkUpdateVariables,
-  G as useCreateVariable,
-  k as useDeleteVariable,
-  j as useUpdateVariable,
-  S as useVariableCollections,
-  B as useVariableModes,
+  B as useCreateVariable,
+  j as useDeleteVariable,
+  G as useUpdateVariable,
+  V as useVariableCollections,
+  k as useVariableModes,
   y as useVariables
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.2",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",