Added CSV Importer example

Author: elmarburke

.env.example

@@ -0,0 +1,2 @@
+FRAMER_PROJECT_URL=https://development.framer.com/projects/Sites--aabbccddeeff
+FRAMER_API_KEY=12345678-1234-1234-1234-123456789

README.md

@@ -0,0 +1,9 @@
+# Framer Server API Examples
+
+This repository contains examples for the Framer Server API. Each example is a standalone project that can be run independently.
+
+## How to run examples
+
+You need to obtain a Framer project URL and API key. You can get them from the Framer project settings.
+
+Then, you need to set the `FRAMER_PROJECT_URL` and `FRAMER_API_KEY` environment variables.

biome.json

@@ -21,7 +21,8 @@
     "linter": {
         "enabled": true,
         "rules": {
-            "recommended": true
+            "recommended": true,
+            "useLiteralKeys": "off"
         }
     },
     "javascript": {

examples/csv-importer/README.md

@@ -0,0 +1,13 @@
+# CSV Importer
+
+This example shows how to import a CSV file into a Framer collection.
+
+How to use:
+
+```bash
+npx tsx --env-file=../../.env src/csv-to-collection.ts
+
+bun run src/csv-to-collection.ts
+
+deno run src/csv-to-collection.ts
+```

examples/csv-importer/data/sample-products.csv

@@ -0,0 +1,9 @@
+slug,title,description,price,inStock,category
+wireless-mouse,Wireless Mouse,Ergonomic wireless mouse with precision tracking,29.99,true,Electronics
+mechanical-keyboard,Mechanical Keyboard,RGB mechanical keyboard with cherry switches,89.99,true,Electronics
+usb-c-cable,USB-C Cable,Fast charging USB-C cable 6ft length,12.99,false,Accessories
+monitor-stand,Monitor Stand,Adjustable aluminum monitor stand,49.99,true,Furniture
+desk-lamp,LED Desk Lamp,Dimmable LED lamp with USB charging port,34.99,true,Lighting
+webcam-hd,HD Webcam,1080p webcam with built-in microphone,59.99,true,Electronics
+mouse-pad,Large Mouse Pad,Extended gaming mouse pad with stitched edges,19.99,true,Accessories
+headphone-stand,Headphone Stand,Wooden headphone stand with cable holder,24.99,false,Furniture

examples/csv-importer/package.json

@@ -7,6 +7,13 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
+        "framer-api": "^0.0.1-alpha.6",
+        "papaparse": "^5.5.3",
         "typescript": "^5.9.3"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2",
+        "@types/papaparse": "^5.3.15",
+        "tsx": "^4.21.0"
     }
 }

examples/csv-importer/src/csv-to-collection.ts

@@ -0,0 +1,95 @@
+import assert from "node:assert";
+import path from "node:path";
+import { type CreateField, connect, type FieldDataEntryInput, type FieldDataInput } from "framer-api";
+import { type FieldType, loadCsv } from "./load-csv";
+
+// Configuration
+
+const projectUrl = process.env["FRAMER_PROJECT_URL"];
+if (!projectUrl) {
+    console.error("FRAMER_PROJECT_URL environment variable is required");
+    process.exit(1);
+}
+
+const csvPath = process.env["CSV_PATH"] ?? path.join(import.meta.dirname, "../data/sample-products.csv");
+const collectionName = process.env["COLLECTION_NAME"] ?? "Products";
+
+const { columns, rows, fieldTypes } = loadCsv(csvPath);
+
+if (!columns.includes("slug")) {
+    console.error("CSV must contain a 'slug' column");
+    process.exit(1);
+}
+
+using framer = await connect(projectUrl);
+
+// Find or Create Collection
+
+const existingCollections = await framer.getCollections();
+let collection = existingCollections.find((c) => c.name === collectionName);
+
+if (!collection) {
+    collection = await framer.createCollection(collectionName);
+}
+
+// Add Missing Fields
+
+const existingFields = await collection.getFields();
+const existingFieldNames = new Set(existingFields.map((f) => f.name.toLowerCase()));
+
+const fieldsToCreate = columns
+    .filter((column) => column !== "slug" && !existingFieldNames.has(column.toLowerCase()))
+    .map(
+        (column): CreateField => ({
+            type: fieldTypes.get(column) ?? "string",
+            name: column,
+        }),
+    );
+
+if (fieldsToCreate.length > 0) {
+    await collection.addFields(fieldsToCreate);
+}
+
+// Build Items & Import
+
+const fields = await collection.getFields();
+const fieldNameToId = new Map(fields.map((f) => [f.name.toLowerCase(), f.id]));
+
+const existingItems = await collection.getItems();
+const slugToExistingId = new Map(existingItems.map((item) => [item.slug, item.id]));
+
+const items = rows.map((row) => {
+    const fieldData: FieldDataInput = {};
+
+    for (const column of columns) {
+        if (column === "slug") continue;
+
+        const fieldId = fieldNameToId.get(column.toLowerCase());
+        if (!fieldId) continue;
+
+        const value = row[column] ?? "";
+        const fieldType = fieldTypes.get(column) ?? "string";
+        fieldData[fieldId] = toFieldData(value, fieldType);
+    }
+
+    const slug = row["slug"];
+    assert(slug && slug.length > 0, "slug is required and must be non-empty");
+    const existingId = slugToExistingId.get(slug);
+
+    return { id: existingId, slug, fieldData };
+});
+
+await collection.addItems(items);
+
+console.log(`Imported ${items.length} items`);
+
+function toFieldData(value: string, type: FieldType): FieldDataEntryInput {
+    switch (type) {
+        case "boolean":
+            return { type: "boolean" as const, value: value.toLowerCase() === "true" };
+        case "number":
+            return { type: "number" as const, value: parseFloat(value) || 0 };
+        case "string":
+            return { type: "string" as const, value };
+    }
+}

examples/csv-importer/src/load-csv.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import Papa from "papaparse";
+
+export type FieldType = "string" | "number" | "boolean";
+
+export interface CsvData {
+    columns: string[];
+    rows: Record<string, string>[];
+    fieldTypes: Map<string, FieldType>;
+}
+
+export function loadCsv(path: string): CsvData {
+    const csvContent = readFileSync(path, "utf-8");
+    const { data: rows, meta } = Papa.parse<Record<string, string>>(csvContent, {
+        header: true,
+        skipEmptyLines: true,
+        transformHeader: (header: string) => header.trim(),
+        transform: (value: string) => value.trim(),
+    });
+
+    if (!meta.fields) {
+        throw new Error("CSV file has no header row");
+    }
+
+    const fieldTypes = new Map(inferFieldTypes(rows, meta.fields));
+
+    return { columns: meta.fields, rows, fieldTypes };
+}
+
+function inferFieldType(values: string[]): FieldType {
+    const nonEmptyValues = values.filter((v) => v !== "");
+    if (nonEmptyValues.length === 0) return "string";
+
+    const allBooleans = nonEmptyValues.every((v) => v === "true" || v === "false");
+    if (allBooleans) return "boolean";
+
+    const allNumbers = nonEmptyValues.every((v) => !Number.isNaN(parseFloat(v)) && Number.isFinite(Number(v)));
+    if (allNumbers) return "number";
+
+    return "string";
+}
+
+/**
+ * Infer the field types from the data in the CSV file.
+ * Returns the column name and the inferred field type.
+ */
+function inferFieldTypes(rows: Record<string, string>[], columns: string[]): [string, FieldType][] {
+    return columns.map((column) => {
+        const values = rows.map((row) => row[column] ?? "");
+        return [column, inferFieldType(values)];
+    });
+}