nuxt-google-sheets-import 0.1.7 → 0.1.9

package/README.md

@@ -1,28 +1,25 @@
 # nuxt-google-sheets-import
 
-Schema-driven Google Sheets importer for Nuxt Content.
+Schema-driven Google Sheets import and export workflows for Nuxt Content.
 
-## Status
+## Documentation
 
-Nuxt module for schema-driven Google Sheets import/export workflows with Nuxt Content.
+Project documentation now lives in the Docus site under [docs/content](docs/content).
 
-## Features
+- Intro: [docs/content/1.getting-started/2.introduction.md](docs/content/1.getting-started/2.introduction.md)
+- Installation: [docs/content/1.getting-started/3.installation.md](docs/content/1.getting-started/3.installation.md)
 
-- Fetches sheet list and values from Google Sheets
-- Validates/transforms rows with Zod schemas
-- Writes frontmatter markdown, JSON, or YAML output
-- Supports overwrite strategies (`overwrite`, `skip`, `overwrite-frontmatter`)
-- Exposes UI components and composables for import workflow
-- Includes a built-in `/google-sheets-import` page with tabbed setup/import/export flow
-- Supports TSV clipboard copy for Google Sheets-friendly paste
+Use this root README as a repo quick-start and contributor guide. Keep long-form user documentation in the docs site.
 
-## Install
+## Module Quick Start
+
+Install:
 
 ```bash
 pnpm add nuxt-google-sheets-import
 ```
 
-## Configuration
+Enable the module:
 
 ```ts
 // nuxt.config.ts
@@ -30,86 +27,33 @@ export default defineNuxtConfig({
   modules: ['nuxt-google-sheets-import'],
   googleSheetsImport: {
     apiBase: '/api/google-sheets-import',
-    googleApiKeyRuntimeKey: 'googleApiKey',
     defaultContentDir: 'content/data'
   }
 })
 ```
 
-Collection type (`page` vs `data`) is derived from your Nuxt Content `content.config.ts` collections.
-
-## Environment
+Environment:
 
 ```bash
 NUXT_GOOGLE_API_KEY=your_google_sheets_api_key
 ```
 
-## Quick Start
-
-1. Add the module and runtime env var.
-2. Define your Zod `schemas` export in `~/utils/googleSheetImportSchemas.ts`.
-3. Ensure matching Nuxt Content collections exist in `content.config.ts`.
-4. Start dev server and open `/google-sheets-import`.
-5. Use tabs in order:
-   - `Setup Google Sheet`: confirm schema headers and copy as needed.
-   - `Import data`: load sheet rows and write content files.
-   - `Export data`: query existing records, copy TSV for Sheets, or download CSV.
-
-Quick endpoint check:
-
-`GET /api/google-sheets-import/sheets?spreadsheetId=<SPREADSHEET_ID>`
+## What The Module Provides
 
-## Exported runtime
+- A built-in route at `/google-sheets-import`
+- Tabbed workflow with schema setup, import, and export steps
+- Zod schema-driven row validation/transforms
+- Writes to markdown frontmatter, JSON, and YAML
+- Export helpers:
+  - copy TSV to clipboard for Google Sheets paste
+  - download CSV
 
-- Components: `GoogleSheetsImportSource`, `GoogleSheetsImportExecute`, `GoogleSheetsImportSchemaGuide`, `GoogleSheetsImportExport`
-- Composables: `useGoogleSheetsImport`, `useGoogleSheetsImportWorkflow`
-
-The module adds a route at `/google-sheets-import` with `UTabs` for:
-
-- `Setup Google Sheet` (schema guide)
-- `Import data` (sheet source/import flow)
-- `Export data` (export existing content records)
-
-### Schema helper component
-
-Use `GoogleSheetsImportSchemaGuide` to let editors choose a schema and see the expected Google Sheet column headers.
-
-```vue
-<GoogleSheetsImportSchemaGuide />
-```
-
-Benefits:
-
-- Reduces import failures by giving editors exact header names before filling a sheet
-- Supports nested/array header patterns used by schema mapping (for example `items[0].name`)
-- Uses a single column for arrays of scalar values (for example `tags` with `foo, bar, baz`)
-- For `page` collections, shows Nuxt Content built-in page override fields and allows copying them separately
-- Supports two copy modes:
-  - line-by-line copy
-  - tab-separated row copy (pastes horizontally into Google Sheets)
-
-Optional prop:
-
-- `initialSchema?: string`
-
-### Suggested Cell Examples
-
-Use these value patterns when filling sheets:
-
-- `string`: `example text`
-- `number`: `123`
-- `boolean`: `true` or `false`
-- `enum` / `literal`: use one of the schema's allowed values
-- `date-like string`: `2026-01-01`
-- `string[]` (scalar array): `foo, bar, baz` in a single cell
-- `object[]` (array of objects): use indexed headers like `items[0].name`, `items[0].price`
+Collection type (`page` vs `data`) is resolved from your Nuxt Content collections.
 
 ## Schema Source
 
-Define a `schemas` export in `~/utils/googleSheetImportSchemas.ts`.
-The module auto-imports this as `googleSheetsImportSchemas` for app and server runtime use.
-
-Example:
+Define and export `schemas` in `~/utils/googleSheetImportSchemas.ts`.
+The module auto-imports it as `googleSheetsImportSchemas` in app and server runtime.
 
 ```ts
 export const schemas = {
@@ -118,93 +62,26 @@ export const schemas = {
 }
 ```
 
-## Export Behavior
+## Repository Development
 
-- `Copy for Google Sheets` in `GoogleSheetsImportExport` copies **TSV** to the clipboard for reliable Sheets paste.
-- `Download .csv` provides quoted CSV output for file-based workflows.
+Module development:
 
-## Additional API Endpoint
-
-- `GET {apiBase}/schema-columns`
-  - Query: `schema?`
-  - Returns:
-    - `schemas`: available schema keys
-    - `columns`: expected import header names for selected schema
-    - `collectionType`: `page | data | unknown`
-    - `pageOverrideColumns`: Nuxt Content page override fields (when `collectionType === 'page'`)
-
-## Google Setup (Permissions + API Key)
-
-This module reads Google Sheets using an API key, so the sheet must be publicly readable.
-
-> Security note:
-> API-key access is best suited to non-sensitive sheets that are intentionally shared as `Anyone with the link`.
-> For private or sensitive spreadsheets, prefer OAuth 2.0 or a service account flow instead of API-key access.
-
-### 1) Set sheet permissions (Google Sheets)
-
-1. Open your sheet in Google Sheets.
-2. Click `Share`.
-3. Under `General access`, set to `Anyone with the link`.
-4. Set role to `Viewer`.
-5. Copy the spreadsheet ID from the URL:
-  - `https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit`
-
-If your Google Workspace policy blocks public link sharing, API key access will fail. In that case you need OAuth/service-account based auth (not part of this module yet).
-
-### 2) Create API key (Google Cloud Console)
-
-1. Open Google Cloud Console: https://console.cloud.google.com/
-2. Create/select a project.
-3. Enable Google Sheets API:
-  - https://console.cloud.google.com/apis/library/sheets.googleapis.com
-4. Create credentials (API key):
-  - https://console.cloud.google.com/apis/credentials
-  - Click `Create credentials` -> `API key`
-5. Restrict the key (recommended):
-  - **API restrictions**: `Restrict key` -> select `Google Sheets API`
-  - **Application restrictions**:
-    - Server usage: `IP addresses` (recommended for backend)
-    - Browser-only usage: `HTTP referrers` (if applicable)
-6. Put the key into `NUXT_GOOGLE_API_KEY`.
-
-### 3) Troubleshooting (common errors)
-
-- `403 PERMISSION_DENIED` / `The caller does not have permission`
-  - The sheet is not publicly readable with link.
-  - Fix: set `Share` -> `General access` -> `Anyone with the link` + `Viewer`.
-
-- `403 API key not valid` or `API has not been used in project`
-  - The key is wrong, restricted to the wrong API, or Sheets API is not enabled.
-  - Fix: enable `Google Sheets API` and ensure key restriction includes it.
-
-- `403 Requests from this referrer/IP are blocked`
-  - Your key application restrictions do not match where requests come from.
-  - Fix: update key restrictions (`IP addresses` for server use is preferred).
-
-- `404 Requested entity was not found`
-  - Spreadsheet ID is incorrect or malformed.
-  - Fix: copy ID from `https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit`.
-
-- `400 Unable to parse range`
-  - Invalid A1 range (for example typo in sheet tab or columns).
-  - Fix: verify tab name and use ranges like `A:Z`.
-
-## Publish checklist
-
-- Add playground integration tests for `/values` and `/write`
-- Add CI (`lint`, `typecheck`, `build`) and release workflow
-- Verify Nuxt 4 peer compatibility matrix
+```bash
+npm install
+npm run dev:prepare
+npm run test
+```
 
-## Release
+Playground app:
 
 ```bash
-npm run release
+npm run dev
 ```
 
-If needed, authenticate and publish manually:
+Docs site:
 
 ```bash
-npm login
-npm publish --access public
+cd docs
+npm install
+npm run dev
 ```

package/dist/module.d.mts

@@ -2,8 +2,11 @@ import * as _nuxt_schema from '@nuxt/schema';
 
 interface ModuleOptions {
     apiBase: string;
-    googleApiKeyRuntimeKey: string;
     defaultContentDir: string;
+    googleSheets: Array<{
+        id: string;
+        label: string;
+    }>;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-google-sheets-import",
   "configKey": "googleSheetsImport",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, extendPages, addServerHandler, addImportsDir, addComponentsDir, addImports, addServerImports } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addTemplate, extendPages, addServerHandler, addImportsDir, addComponentsDir, addImports, addServerImports } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -15,28 +15,35 @@ const module$1 = defineNuxtModule({
   },
   defaults: {
     apiBase: "/api/google-sheets-import",
-    googleApiKeyRuntimeKey: "googleApiKey",
-    defaultContentDir: "content/data"
+    defaultContentDir: "content/data",
+    googleSheets: []
   },
   setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
+    addTemplate({
+      filename: "googleSheetsImportSchemas.ts",
+      src: resolver.resolve("./runtime/app/examples/googleSheetsImportSchemas.ts"),
+      dst: "utils/.googleSheetsImportSchemas.ts",
+      write: true
+    });
     nuxt.options.runtimeConfig.googleSheetsImport = {
       ...nuxt.options.runtimeConfig.googleSheetsImport,
       apiBase: options.apiBase,
-      googleApiKeyRuntimeKey: options.googleApiKeyRuntimeKey,
-      defaultContentDir: options.defaultContentDir
+      defaultContentDir: options.defaultContentDir,
+      googleSheets: options.googleSheets
     };
     nuxt.options.runtimeConfig.public.googleSheetsImport = {
       ...nuxt.options.runtimeConfig.public.googleSheetsImport,
       apiBase: options.apiBase,
-      defaultContentDir: options.defaultContentDir
+      defaultContentDir: options.defaultContentDir,
+      googleSheets: options.googleSheets
     };
-    nuxt.options.css.push(resolver.resolve("./runtime/assets/css/main.css"));
+    nuxt.options.css.push(resolver.resolve("./runtime/app/assets/css/main.css"));
     extendPages((pages) => {
       pages.push({
         name: "google-sheets-import",
         path: "/google-sheets-import",
-        file: resolver.resolve("./runtime/pages/google-sheets-import.vue")
+        file: resolver.resolve("./runtime/app/pages/google-sheets-import.vue")
       });
     });
     addServerHandler({
@@ -64,16 +71,11 @@ const module$1 = defineNuxtModule({
       method: "post",
       handler: resolver.resolve("./runtime/server/api/write.post")
     });
-    addImportsDir(resolver.resolve("./runtime/composables"));
+    addImportsDir(resolver.resolve("./runtime/app/composables"));
     addComponentsDir({
-      path: resolver.resolve("./runtime/components")
+      path: resolver.resolve("./runtime/app/components")
     });
     addImports([
-      {
-        from: "~/utils/googleSheetImportSchemas",
-        name: "schemas",
-        as: "googleSheetsImportSchemas"
-      },
       {
         from: resolver.resolve("./runtime/types/googleSheetsApi"),
         name: "GoogleSheetsApiValues",
@@ -107,8 +109,8 @@ const module$1 = defineNuxtModule({
     ]);
     addServerImports([
       {
-        from: "~/utils/googleSheetImportSchemas",
-        name: "schemas",
+        from: "~/utils/googleSheetsImportSchemas",
+        name: "googleSheetsImportSchemas",
         as: "googleSheetsImportSchemas"
       }
     ]);

package/dist/runtime/{components → app/components}/GoogleSheetsImportExecute.vue

@@ -12,9 +12,9 @@ const outputFormatOptions = [
   { label: "YAML (.yml)", value: "yaml" }
 ];
 const overwriteModeOptions = [
-  { label: "Overwrite existing files", value: "overwrite" },
-  { label: "Skip files that already exist", value: "skip" },
-  { label: "Overwrite frontmatter only (.md only)", value: "overwrite-frontmatter" }
+  { label: "Skip existing files", value: "skip" },
+  { label: "Overwrite frontmatter only (.md files)", value: "overwrite-frontmatter" },
+  { label: "Overwrite all", value: "overwrite" }
 ];
 const {
   status,

package/dist/runtime/{components → app/components}/GoogleSheetsImportExport.vue

@@ -1,11 +1,17 @@
 <script setup>
 import { computed, ref, watch } from "vue";
-import { googleSheetsImportSchemas, queryCollection, useAsyncData, useToast } from "#imports";
+import { queryCollection, useAsyncData, useToast } from "#imports";
+import { useGoogleSheetsImport } from "../composables/useGoogleSheetsImport";
 import { copyTextWithSuccessToast } from "../utils/clipboard";
 import { toCsvRow, toTsvRow } from "../utils/delimited";
 import { flattenRecordToStringMap } from "../utils/pathMapping";
 const toast = useToast();
-const queryCollectionLoose = queryCollection;
+const { getSchemaColumns } = useGoogleSheetsImport();
+const queryCollectionAny = queryCollection;
+function queryCollectionRows(collection) {
+  const query = queryCollectionAny(collection);
+  return query.all();
+}
 const selectedSchema = ref("");
 const {
   data: rowsData,
@@ -15,26 +21,36 @@ const {
   execute,
   clear
 } = useAsyncData(
-  "google-sheets-import-export-records",
   async () => {
     if (!selectedSchema.value) {
       return [];
     }
-    const result = await queryCollectionLoose(selectedSchema.value).all();
-    return result;
+    return await queryCollectionRows(selectedSchema.value);
   },
   {
     immediate: false,
     default: () => []
   }
 );
+const {
+  data: schemaNames,
+  error: schemaNamesError
+} = useAsyncData(
+  "google-sheets-import-export-schemas",
+  async () => {
+    const response = await getSchemaColumns();
+    return response.schemas ?? [];
+  },
+  {
+    default: () => []
+  }
+);
 const rows = computed(() => rowsData.value ?? []);
-const error = computed(() => loadError.value?.message ?? "");
+const error = computed(() => loadError.value?.message ?? schemaNamesError.value?.message ?? "");
 watch(selectedSchema, () => {
   clear();
 });
-const schemaMap = computed(() => googleSheetsImportSchemas ?? {});
-const schemaOptions = computed(() => Object.keys(schemaMap.value).sort((left, right) => left.localeCompare(right)).map((schema) => ({ label: schema, value: schema })));
+const schemaOptions = computed(() => (schemaNames.value ?? []).sort((left, right) => left.localeCompare(right)).map((schema) => ({ label: schema, value: schema })));
 const headers = computed(() => {
   const all = /* @__PURE__ */ new Set();
   for (const row of rows.value) {

package/dist/runtime/app/examples/googleSheetsImportSchemas.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const googleSheetsImportSchemas: {
+    example: z.ZodObject<{
+        slug: z.ZodString;
+        pageOrder: z.ZodCoercedNumber<unknown>;
+        number: z.ZodCoercedNumber<unknown>;
+        string: z.ZodString;
+        enumString: z.ZodEnum<{
+            foo: "foo";
+            bar: "bar";
+            baz: "baz";
+        }>;
+        literalString: z.ZodLiteral<"foo">;
+        unionString: z.ZodUnion<readonly [z.ZodLiteral<"foo">, z.ZodLiteral<"bar">]>;
+        unionStringArray: z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"foo">, z.ZodLiteral<"bar">]>>;
+        exclusiveUnionString: z.ZodXor<readonly [z.ZodLiteral<"foo">, z.ZodLiteral<"bar">]>;
+        stringArray: z.ZodArray<z.ZodString>;
+        numberArray: z.ZodArray<z.ZodCoercedNumber<unknown>>;
+        boolean: z.ZodCoercedBoolean<unknown>;
+        object: z.ZodObject<{
+            key1: z.ZodString;
+            key2: z.ZodString;
+        }, z.core.$strip>;
+        objectArray: z.ZodArray<z.ZodObject<{
+            keyA: z.ZodString;
+            keyB: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};

package/dist/runtime/app/examples/googleSheetsImportSchemas.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+const example = z.object({
+  slug: z.string().min(1).max(100),
+  pageOrder: z.coerce.number().int(),
+  number: z.coerce.number(),
+  string: z.string().min(1).max(100),
+  enumString: z.enum(["foo", "bar", "baz"]),
+  literalString: z.literal("foo"),
+  unionString: z.union([z.literal("foo"), z.literal("bar")]),
+  unionStringArray: z.union([z.literal("foo"), z.literal("bar")]).array(),
+  exclusiveUnionString: z.xor([z.literal("foo"), z.literal("bar")]),
+  stringArray: z.string().array(),
+  numberArray: z.coerce.number().array(),
+  boolean: z.coerce.boolean(),
+  object: z.object({
+    key1: z.string().min(1),
+    key2: z.string().min(1)
+  }),
+  objectArray: z.array(
+    z.object({
+      keyA: z.string().min(1),
+      keyB: z.string().min(1)
+    })
+  )
+});
+export const googleSheetsImportSchemas = {
+  example
+};

package/dist/runtime/{pages → app/pages}/google-sheets-import.vue

@@ -1,9 +1,8 @@
 <script setup>
 import { ref } from "vue";
-const sheetsList = ref([
-  { id: "1NKS0cTX6u5urtgQ3Q4Z2motiR2-9JmyPxcd05yVc1bc", label: "Metzner" },
-  { id: "1tGZCEoiikXfg3mOpfVWWTS1SSSsj18xv6Z3owrnnt4s", label: "Example Sheet" }
-]);
+import { useRuntimeConfig } from "#imports";
+const config = useRuntimeConfig();
+const sheetsList = config.public.googleSheetsImport?.googleSheets ?? [];
 const items = ref([
   {
     label: "Setup Google Sheet",

package/dist/runtime/server/api/sheets.get.js

@@ -6,8 +6,8 @@ const querySchema = z.object({
   spreadsheetId: z.string().length(44)
 });
 export default defineEventHandler(async (event) => {
-  const { googleSheetsImport } = useRuntimeConfig();
-  const apiKey = googleSheetsImport?.googleApiKeyRuntimeKey;
+  const config = useRuntimeConfig(event);
+  const apiKey = config.googleApiKey;
   const { spreadsheetId } = await getValidatedQuery(event, (query) => querySchema.parse(query));
   if (!apiKey || typeof apiKey !== "string") {
     throw createError({ statusCode: 500, statusMessage: `Missing Google API key in nuxt.config googleSheetsImport: { googleApiKeyRuntimeKey: '${apiKey}' }` });

package/dist/runtime/server/api/values.post.js

@@ -10,8 +10,8 @@ const bodySchema = z.object({
 });
 export default defineEventHandler(async (event) => {
   const body = bodySchema.parse(await readBody(event));
-  const { googleSheetsImport } = useRuntimeConfig();
-  const apiKey = googleSheetsImport?.googleApiKeyRuntimeKey;
+  const config = useRuntimeConfig(event);
+  const apiKey = config.googleApiKey;
   if (!apiKey || typeof apiKey !== "string") {
     throw createError({ statusCode: 500, statusMessage: `Missing Google API key in nuxt.config googleSheetsImport: { googleApiKeyRuntimeKey: '${apiKey}' }` });
   }

package/dist/runtime/server/utils/transform.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { parseHeaderPath, setDeep } from "../../utils/pathMapping.js";
+import { parseHeaderPath, setDeep } from "../../../runtime/app/utils/pathMapping";
 function isZodType(value) {
   return typeof value === "object" && value !== null && "_def" in value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-google-sheets-import",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Schema-driven Google Sheets import module for Nuxt Content",
   "repository": "tribeweb/nuxt-google-sheets-import",
   "license": "MIT",
@@ -23,9 +23,12 @@
     "dist"
   ],
   "workspaces": [
-    "playground"
+    "playground",
+    "docs"
   ],
   "scripts": {
+    "docs:dev": "cd docs && nuxt dev --extends docus",
+    "docs:build": "nuxt build docs --extends docus",
     "prepack": "nuxt-module-build build",
     "dev": "npm run dev:prepare && nuxt dev playground",
     "dev:build": "nuxt build playground",