fix: handle invalid Figma credentials gracefully

Author: onmax

packages/nimiq-icons/.env.example

@@ -1,4 +1,16 @@
 # Figma API credentials for icon generation
-# If these are not set, the icon build script will be skipped
-FIGMA_FILE_ID=your_figma_file_id_here
-FIGMA_API_TOKEN=your_figma_api_token_here
+# These are ONLY needed if you're actively working on updating the icons from Figma
+# Most developers can ignore this file - the icon build will be automatically skipped
+
+# How to set up (only if you need to update icons):
+# 1. Get a Figma API token from https://www.figma.com/developers/api#access-tokens
+# 2. Get the File ID from the Figma file URL: https://www.figma.com/file/{FILE_ID}/...
+# 3. Uncomment and fill in the values below
+# 4. Make sure you have access to the Nimiq Figma file
+
+# FIGMA_FILE_ID=your_figma_file_id_here
+# FIGMA_API_TOKEN=your_figma_api_token_here
+
+# Note: If you see a 404 error when running pnpm dev, either:
+# - Delete this .env file (if you don't need to update icons)
+# - OR verify you have the correct credentials and access permissions above

packages/nimiq-icons/README.md

@@ -18,13 +18,30 @@ You can preview the icons in the `apps/icons-ui` directory. This directory conta
 
 ## Environment Variables
 
-The package requires the following environment variables:
+The package uses the following environment variables for Figma integration:
 
 ```bash
-FIGMA_FILE_ID: The ID of the Figma file.
-FIGMA_API_TOKEN: The API token for Figma.
+FIGMA_FILE_ID: The ID of the Figma file
+FIGMA_API_TOKEN: The API token for Figma
 ```
 
+**Important:** These are ONLY required if you're actively working on updating icons from Figma. Most developers can ignore this - the icon build will automatically skip if credentials are not configured.
+
+### Setup for Icon Development
+
+1. Copy `.env.example` to `.env` in the `packages/nimiq-icons` directory
+2. Get a Figma API token from https://www.figma.com/developers/api#access-tokens
+3. Get the File ID from the Nimiq Figma file URL
+4. Fill in the values in your `.env` file
+5. Ensure you have access permissions to the Nimiq Figma file
+
+### Troubleshooting
+
+If you encounter a 404 error when running `pnpm dev`:
+
+- **Don't need to update icons?** Delete the `.env` file - the build will skip automatically
+- **Need to update icons?** Verify your credentials are correct and you have access to the Figma file
+
 ## Scripts
 
-The package provides a dev script that you can run with npm run dev. This script uses bun to compile the TypeScript source code.
+The package provides a dev script that you can run with `pnpm dev`. This script processes icons from Figma and generates the icon packages.

packages/nimiq-icons/scripts/index.ts

@@ -66,32 +66,40 @@ async function checkFigmaVariants() {
 
   const { file, token } = credentials
 
-  const figma = await importFromFigma({
-    file,
-    pages: ['Main'],
-    token,
-    prefix: 'nimiq',
-    depth: 2,
-    ifModifiedSince: '2021-01-01T00:00:00Z', // Force fetch to ensure variants exist
-    iconNameForNode: node => node.name.startsWith('_') ? null : node.name,
-    simplifyStroke: true,
-  })
+  try {
+    const figma = await importFromFigma({
+      file,
+      pages: ['Main'],
+      token,
+      prefix: 'nimiq',
+      depth: 2,
+      ifModifiedSince: '2021-01-01T00:00:00Z', // Force fetch to ensure variants exist
+      iconNameForNode: node => node.name.startsWith('_') ? null : node.name,
+      simplifyStroke: true,
+    })
 
-  if (figma === 'not_modified') {
-    consola.info('Figma file has not been modified since last check. Will use cached data.')
-    return
-  }
+    if (figma === 'not_modified') {
+      consola.info('Figma file has not been modified since last check. Will use cached data.')
+      return
+    }
 
-  const iconSetVariants = figma.iconSet.list().map(sanitizeName)
-  const ourVariants = Object.values(IconVariant)
+    const iconSetVariants = figma.iconSet.list().map(sanitizeName)
+    const ourVariants = Object.values(IconVariant)
 
-  const missingVariants = ourVariants.filter(variant => !iconSetVariants.includes(variant))
-  const extraUnknownVariants = iconSetVariants.filter(v => !ourVariants.includes(v as IconVariant))
+    const missingVariants = ourVariants.filter(variant => !iconSetVariants.includes(variant))
+    const extraUnknownVariants = iconSetVariants.filter(v => !ourVariants.includes(v as IconVariant))
 
-  if (missingVariants.length > 0 || extraUnknownVariants.length > 0)
-    throw new Error(`There is an unknown variant or a missing variant: ${JSON.stringify({ extraUnknownVariants, missingVariants })}`)
+    if (missingVariants.length > 0 || extraUnknownVariants.length > 0)
+      throw new Error(`There is an unknown variant or a missing variant: ${JSON.stringify({ extraUnknownVariants, missingVariants })}`)
 
-  consola.success('Figma variants are correct.')
+    consola.success('Figma variants are correct.')
+  }
+  catch {
+    consola.warn('Could not access Figma file. This might be due to invalid credentials or insufficient permissions.')
+    consola.warn('Icon build will be skipped. If you need to update icons, please check your FIGMA_FILE_ID and FIGMA_API_TOKEN in .env')
+    consola.info('Tip: If you don\'t need to modify icons, you can delete the .env file to skip this check entirely.')
+    return null
+  }
 }
 
 async function getFigma(frameName: string) {
@@ -363,7 +371,11 @@ async function main() {
     return
   }
 
-  await checkFigmaVariants()
+  const variantsCheck = await checkFigmaVariants()
+  if (variantsCheck === null) {
+    consola.info('Skipping Figma icon build due to credential issues')
+    return
+  }
   consola.start('Processing icon variants...')
 
   // Object to store all icon sets