form-to-google-sheet 1.0.0

package/Code.gs

@@ -0,0 +1,56 @@
+// ===========================================================
+// Google Apps Script — paste this into your Sheet's script editor
+// (Extensions > Apps Script), then deploy as a Web App.
+// ===========================================================
+
+var SHEET_NAME = "Sheet1"; // change if your tab has a different name
+
+function doPost(e) {
+  try {
+    var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(SHEET_NAME);
+    if (!sheet) {
+      return _jsonResponse(404, { error: "Sheet '" + SHEET_NAME + "' not found" });
+    }
+
+    var data = JSON.parse(e.postData.contents);
+    var rows = data.rows || [data]; // accept a single object or { rows: [...] }
+
+    var headers = sheet.getRange(1, 1, 1, sheet.getLastColumn()).getValues()[0].filter(String);
+
+    if (headers.length === 0) {
+      // Sheet is empty — use the keys from the first row as headers
+      headers = Object.keys(rows[0]);
+      sheet.getRange(1, 1, 1, headers.length).setValues([headers]);
+    }
+
+    var output = [];
+    rows.forEach(function (row) {
+      var newRow = headers.map(function (header) {
+        return row[header] !== undefined ? row[header] : "";
+      });
+      sheet.appendRow(newRow);
+      output.push(newRow);
+    });
+
+    return _jsonResponse(200, {
+      status: "ok",
+      rowsAdded: output.length,
+      headers: headers,
+    });
+  } catch (err) {
+    return _jsonResponse(500, { error: err.message });
+  }
+}
+
+function doGet() {
+  return _jsonResponse(200, {
+    status: "ok",
+    message: "FormToGoogleSheet endpoint is live. Send a POST to add rows.",
+  });
+}
+
+function _jsonResponse(code, payload) {
+  return ContentService.createTextOutput(JSON.stringify(payload)).setMimeType(
+    ContentService.MimeType.JSON
+  );
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# FormToGoogleSheet
+
+Submit HTML form data straight to a Google Sheet. No API keys, no server, no database — just a Google Sheet and a `<script>` tag.
+
+## Install
+
+```bash
+npm install form-to-google-sheet
+```
+
+Or use a CDN — no install needed:
+
+```html
+<script src="https://unpkg.com/form-to-google-sheet"></script>
+```
+
+Or with jsdelivr:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/form-to-google-sheet"></script>
+```
+
+## How It Works
+
+```
+Browser form  ──POST──▶  Google Apps Script (free)  ──▶  Google Sheet
+```
+
+Google Apps Script acts as a tiny serverless endpoint that lives inside your spreadsheet. You deploy it once, get a URL, and POST to it from anywhere.
+
+---
+
+## Setup (5 minutes)
+
+### 1. Prepare your Google Sheet
+
+Open your sheet and add **column headers** in Row 1.  
+The header names must match the keys you send from your form.
+
+| name | email | message |
+|------|-------|---------|
+|      |       |         |
+
+> If the sheet is empty (no headers), the script will auto-create headers from the first submission's keys.
+
+### 2. Add the Apps Script
+
+1. In your Google Sheet go to **Extensions → Apps Script**.
+2. Delete any code in the editor and paste the contents of [`Code.gs`](Code.gs).
+3. If your tab is not called `Sheet1`, update the `SHEET_NAME` variable at the top.
+4. Click **💾 Save**.
+
+### 3. Deploy as a Web App
+
+1. In the Apps Script editor click **Deploy → New deployment**.
+2. Click the gear icon next to **Select type** and choose **Web app**.
+3. Set:
+   - **Description**: anything you like
+   - **Execute as**: **Me**
+   - **Who has access**: **Anyone**
+4. Click **Deploy**.
+5. Authorize the script when prompted (it needs permission to edit *your* sheet).
+6. Copy the **Web app URL** — it looks like:  
+   `https://script.google.com/macros/s/AKfycb.../exec`
+
+### 4. Add to Your Project
+
+**With npm / a bundler (React, Next.js, Vite, etc.):**
+
+```js
+import FormToSheet from "form-to-google-sheet";
+
+FormToSheet.init("https://script.google.com/macros/s/YOUR_ID/exec");
+```
+
+**With a CDN / script tag (plain HTML):**
+
+```html
+<script src="https://unpkg.com/form-to-google-sheet"></script>
+<script>
+  FormToSheet.init("https://script.google.com/macros/s/YOUR_ID/exec");
+</script>
+```
+
+---
+
+## Usage
+
+### Option A: Bind to a `<form>`
+
+```html
+<form id="contact-form">
+  <input name="name"    required />
+  <input name="email"   required />
+  <textarea name="message"></textarea>
+  <button type="submit">Send</button>
+</form>
+
+<script src="form-to-sheet.js"></script>
+<script>
+  FormToSheet.init("YOUR_APPS_SCRIPT_URL");
+  FormToSheet.bind("#contact-form", {
+    onSuccess: () => alert("Saved!"),
+    onError:   (err) => console.error(err),
+    resetOnSuccess: true,           // default: true
+  });
+</script>
+```
+
+### Option B: Submit Programmatically
+
+```js
+FormToSheet.init("YOUR_APPS_SCRIPT_URL");
+
+// single row
+FormToSheet.submit({ name: "Ada", email: "ada@example.com" })
+  .then(console.log);
+
+// multiple rows at once
+FormToSheet.submit([
+  { name: "Ada",   email: "ada@example.com" },
+  { name: "Grace", email: "grace@example.com" },
+]);
+```
+
+### Option C: Use in React
+
+```jsx
+import { useRef } from "react";
+import FormToSheet from "form-to-google-sheet";
+
+FormToSheet.init("YOUR_APPS_SCRIPT_URL");
+
+export default function ContactForm() {
+  const formRef = useRef(null);
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const data = Object.fromEntries(new FormData(formRef.current));
+    await FormToSheet.submit(data);
+    alert("Done!");
+    formRef.current.reset();
+  };
+
+  return (
+    <form ref={formRef} onSubmit={handleSubmit}>
+      <input name="name" required />
+      <input name="email" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+Tip: call `FormToSheet.init(url)` once at app startup (e.g. in `main.jsx`) instead of per-component if you prefer.
+
+---
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `FormToSheet.init(url)` | Set the Apps Script deployment URL. Call once. |
+| `FormToSheet.submit(data)` | Send a row (`{}`) or rows (`[{}, ...]`). Returns a `Promise`. |
+| `FormToSheet.bind(selector, opts)` | Auto-wire a `<form>` element. Options: `onSuccess`, `onError`, `resetOnSuccess`. |
+
+---
+
+## Notes
+
+- **No API key required.** The Google Apps Script web app handles auth.
+- **CORS**: The library uses `mode: "no-cors"` so it works from any origin. The trade-off is you can't read the response body — but the row still gets written. If the fetch doesn't throw, it worked.
+- **Rate limits**: Google Apps Script allows ~20,000 calls/day on a free Google account. More than enough for contact forms and small apps.
+- **Security**: Anyone with the URL can POST to your sheet. For production, consider adding a shared secret or honeypot field in the Apps Script.

package/form-to-sheet.js

@@ -0,0 +1,106 @@
+/**
+ * 
+ * Sahil Bambulkar (https://www.linkedin.com/in/sahil-bambulkar/)
+ * FormToGoogleSheet — tiny client library (no dependencies, ~1 KB)
+ *
+ * Usage (script tag):
+ *   <script src="form-to-sheet.js"></script>
+ *   <script>
+ *     FormToSheet.init("https://script.google.com/macros/s/YOUR_DEPLOY_ID/exec");
+ *     FormToSheet.submit({ name: "Ada", email: "ada@example.com" });
+ *   </script>
+ *
+ * Usage (ES module):
+ *   import { init, submit } from "./form-to-sheet.js";
+ *   init("https://script.google.com/macros/s/YOUR_DEPLOY_ID/exec");
+ *   submit({ name: "Ada", email: "ada@example.com" });
+ */
+(function (root, factory) {
+  if (typeof module === "object" && module.exports) {
+    module.exports = factory();
+  } else if (typeof define === "function" && define.amd) {
+    define(factory);
+  } else {
+    root.FormToSheet = factory();
+  }
+})(typeof self !== "undefined" ? self : this, function () {
+  "use strict";
+
+  var _url = "";
+
+  function init(scriptUrl) {
+    if (!scriptUrl) throw new Error("[FormToSheet] Missing Apps Script URL");
+    _url = scriptUrl.replace(/\/+$/, "");
+  }
+
+  function _ensureInit() {
+    if (!_url)
+      throw new Error(
+        "[FormToSheet] Call FormToSheet.init(url) before submitting"
+      );
+  }
+
+  /**
+   * Submit a single row (object) or multiple rows (array of objects).
+   * Returns a Promise that resolves with the Apps Script JSON response.
+   */
+  function submit(data) {
+    _ensureInit();
+    var body = Array.isArray(data) ? { rows: data } : data;
+
+    return fetch(_url, {
+      method: "POST",
+      mode: "no-cors",
+      headers: { "Content-Type": "text/plain" },
+      body: JSON.stringify(body),
+    }).then(function (res) {
+      // Google Apps Script redirects and returns opaque responses in no-cors
+      // mode, so we can't reliably read the body. If the fetch didn't throw,
+      // the request was accepted.
+      if (res.type === "opaque") {
+        return { status: "ok", note: "opaque response (no-cors mode)" };
+      }
+      return res.json();
+    });
+  }
+
+  /**
+   * Convenience: bind to a <form> element. On submit it reads all named
+   * inputs, sends them to the sheet, and calls your callback.
+   *
+   *   FormToSheet.bind("#my-form", {
+   *     onSuccess: () => alert("Saved!"),
+   *     onError:   (err) => console.error(err),
+   *   });
+   */
+  function bind(selectorOrEl, opts) {
+    _ensureInit();
+    opts = opts || {};
+    var form =
+      typeof selectorOrEl === "string"
+        ? document.querySelector(selectorOrEl)
+        : selectorOrEl;
+
+    if (!form) throw new Error("[FormToSheet] Form not found: " + selectorOrEl);
+
+    form.addEventListener("submit", function (e) {
+      e.preventDefault();
+      var formData = new FormData(form);
+      var row = {};
+      formData.forEach(function (value, key) {
+        row[key] = value;
+      });
+
+      submit(row)
+        .then(function (res) {
+          if (opts.onSuccess) opts.onSuccess(res);
+          if (opts.resetOnSuccess !== false) form.reset();
+        })
+        .catch(function (err) {
+          if (opts.onError) opts.onError(err);
+        });
+    });
+  }
+
+  return { init: init, submit: submit, bind: bind };
+});

package/index.mjs

@@ -0,0 +1,59 @@
+let _url = "";
+
+function init(scriptUrl) {
+  if (!scriptUrl) throw new Error("[FormToSheet] Missing Apps Script URL");
+  _url = scriptUrl.replace(/\/+$/, "");
+}
+
+function _ensureInit() {
+  if (!_url)
+    throw new Error(
+      "[FormToSheet] Call FormToSheet.init(url) before submitting"
+    );
+}
+
+export function submit(data) {
+  _ensureInit();
+  const body = Array.isArray(data) ? { rows: data } : data;
+
+  return fetch(_url, {
+    method: "POST",
+    mode: "no-cors",
+    headers: { "Content-Type": "text/plain" },
+    body: JSON.stringify(body),
+  }).then((res) => {
+    if (res.type === "opaque") {
+      return { status: "ok", note: "opaque response (no-cors mode)" };
+    }
+    return res.json();
+  });
+}
+
+export function bind(selectorOrEl, opts = {}) {
+  _ensureInit();
+  const form =
+    typeof selectorOrEl === "string"
+      ? document.querySelector(selectorOrEl)
+      : selectorOrEl;
+
+  if (!form)
+    throw new Error("[FormToSheet] Form not found: " + selectorOrEl);
+
+  form.addEventListener("submit", (e) => {
+    e.preventDefault();
+    const formData = new FormData(form);
+    const row = Object.fromEntries(formData);
+
+    submit(row)
+      .then((res) => {
+        if (opts.onSuccess) opts.onSuccess(res);
+        if (opts.resetOnSuccess !== false) form.reset();
+      })
+      .catch((err) => {
+        if (opts.onError) opts.onError(err);
+      });
+  });
+}
+
+export { init };
+export default { init, submit, bind };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "form-to-google-sheet",
+  "version": "1.0.0",
+  "description": "Submit HTML form data straight to a Google Sheet. No API keys, no server, no database.",
+  "main": "form-to-sheet.js",
+  "module": "index.mjs",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./form-to-sheet.js",
+      "default": "./form-to-sheet.js"
+    }
+  },
+  "browser": "form-to-sheet.js",
+  "unpkg": "form-to-sheet.js",
+  "jsdelivr": "form-to-sheet.js",
+  "files": [
+    "form-to-sheet.js",
+    "index.mjs",
+    "Code.gs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "google-sheets",
+    "google-sheet",
+    "form",
+    "form-submit",
+    "spreadsheet",
+    "google-apps-script",
+    "no-server",
+    "serverless"
+  ],
+  "author": "Sahil",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sahil/form-to-google-sheet.git"
+  },
+  "homepage": "https://github.com/sahil/form-to-google-sheet#readme",
+  "bugs": {
+    "url": "https://github.com/sahil/form-to-google-sheet/issues"
+  }
+}