Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
initClefbase
✓ import { initClefbase } from 'clefbase';
✗ const initClefbase = require('clefbase').initClefbase;
Clefbase is primarily an ESM package since v2, requiring ES module import syntax. CommonJS 'require' will not work correctly.
getDatabase, getAuth, getStorage, getHosting, getFunctions, getAI
✓ import { getDatabase, getAuth } from 'clefbase';
✗ import getDatabase from 'clefbase/getDatabase';
These are named exports for accessing specific Clefbase services after initializing the app. Do not attempt to import them from subpaths or as default exports.
FieldValue
✓ import { FieldValue } from 'clefbase';
✗ import FieldValue from 'clefbase/FieldValue';
FieldValue provides helper functions like `increment`, `serverTimestamp`, and `arrayUnion` for atomic updates to database fields. It's a named export from the main package.
Demonstrates initializing Clefbase, adding/getting documents, querying, and user authentication with basic error handling, using environment variable fallbacks for configuration.
import { initClefbase, getDatabase, getAuth } from "clefbase";
// Assume clefbase.json exists from 'npx clefbase init'
// For local development or CI, ensure these are available.
// In a real application, config would typically be loaded securely.
import config from "./clefbase.json";
// In a real application, avoid hardcoding sensitive data.
// Use process.env for API Key and Admin Secret, or a secure configuration management.
// For demonstration, we'll assume config has necessary values or use fallbacks.
const app = initClefbase({
projectId: config.projectId ?? process.env.CLEFBASE_PROJECT_ID ?? 'YOUR_PROJECT_ID',
apiKey: config.apiKey ?? process.env.CLEFBASE_API_KEY ?? 'YOUR_API_KEY',
adminSecret: config.adminSecret ?? process.env.CLEFBASE_ADMIN_SECRET ?? '' // Optional, for admin functions
});
const db = getDatabase(app);
const auth = getAuth(app);
async function runExample() {
console.log("Initializing Clefbase application...");
// Example: Add a new document
const newPost = await db.collection("demoPosts").add({
title: "My First Clefbase Post",
content: "This is a demonstration of adding a document to Clefbase.",
authorId: "user-123",
published: true,
createdAt: new Date().toISOString()
});
console.log(`Added post with ID: ${newPost.id}`);
// Example: Get the document back
const fetchedPost = await db.collection("demoPosts").doc(newPost.id).get();
console.log("Fetched post title:", fetchedPost?.title);
// Example: Basic query for published posts
const publishedPosts = await db.collection("demoPosts")
.where({ published: true })
.getDocs();
console.log(`Found ${publishedPosts.length} published posts.`);
// Example: Sign up a dummy user (handle existing user gracefully for repeated runs)
try {
const { user } = await auth.signUp("example@clefbase.com", "securePassword123", {
displayName: "Demo User",
});
console.log(`Signed up user: ${user.displayName} (ID: ${user.uid})`);
} catch (error: any) {
if (error.message.includes("User already exists")) {
console.log("User already exists, attempting to sign in.");
const { user } = await auth.signIn("example@clefbase.com", "securePassword123");
console.log(`Signed in user: ${user.displayName} (ID: ${user.uid})`);
} else {
console.error("Auth error:", error.message);
}
}
}
runExample().catch(console.error);
clefbase --version
Errors
Common errors & fixes
TypeError: initClefbase is not a function
Attempting to import `initClefbase` using CommonJS `require()` syntax in an ES Module context, or vice-versa.
fixEnsure your project uses ES Modules (`import ... from 'pkg'`) and is configured with `'type': 'module'` in `package.json` for Node.js, or use a bundler that handles ESM correctly.
ClefbaseError: PROJECT_ID_MISSING: Project ID is required for SDK initialization.
The `projectId` or `apiKey` is missing or invalid in the configuration object passed to `initClefbase`.
fixRun `npx clefbase init` to generate a valid `clefbase.json` or ensure that `projectId` and `apiKey` are correctly provided via environment variables or a manually constructed config object.
ClefbaseError: Permission denied (403): Invalid Admin Secret or insufficient permissions for operation.
Attempting to use an API requiring elevated privileges (e.g., `getHosting`, certain database operations) without a valid `adminSecret` in the configuration.
fixProvide the correct `adminSecret` in your Clefbase configuration. Ensure it is loaded securely from environment variables and is never exposed in client-side code.
TypeError: Cannot read properties of null (reading 'id')
Accessing properties on a document object returned by `db.collection(...).doc(...).get()` without checking if the document exists (i.e., if it's `null`).
fixAlways check if the document object is not `null` before attempting to access its properties: `const user = await db.getDoc('users', 'uid-123'); if (user) { console.log(user.id); }`. Audit
Dependencies
reactoptionalPeer dependency for front-end integration, likely for specific client-side features or component bindings not shown in the core SDK example.
react-domoptionalPeer dependency for front-end integration, closely tied with 'react'.