diff --git a/.optimize-cache.json b/.optimize-cache.json index 026b4f4e5c..162237ca53 100644 --- a/.optimize-cache.json +++ b/.optimize-cache.json @@ -220,6 +220,7 @@ "images/blog/appwrite-decoded-khushboo/khushboo-tech-interviews.png": "c54715b658aa52f4c7139e7a1398b9a0e0cb55bcc3aa3dd9101f6164e0bd3379", "images/blog/appwrite-decoded-khushboo/khushboo-with-eldad.png": "b358b6a53d2c5de662b7ddf66aeeb6886478d98c5585a5e2f7068422986cba60", "images/blog/appwrite-decoded/cover-sara.png": "03ef95d81d475dde4caae31c0b442271c8ae904f8655013a2dfe2f8878b97e44", + "images/blog/appwrite-generate/cover.png": "01770d4d6124b317a5103ced1d69b791ef0ce1f1e3a47e4b5072a5fd33c4953d", "images/blog/appwrite-homepage-redesign/cover-image.png": "bc09d91c421f5967c8986eeaae6f7f001380bee686cd3371fd63a8392484647e", "images/blog/appwrite-homepage-redesign/iterations-top-part.png": "713613e719366db8d271ab58815ce5f6db476c0b6a764ce53b4884ddd483f66c", "images/blog/appwrite-homepage-redesign/new-homepage.png": "e58cdf775e1f23ab71e205e0a9d1f6a8573d6e55d673b1a6190be6a79e4e43f0", diff --git a/src/routes/blog/post/appwrite-generate/+page.markdoc b/src/routes/blog/post/appwrite-generate/+page.markdoc new file mode 100644 index 0000000000..9086b43e73 --- /dev/null +++ b/src/routes/blog/post/appwrite-generate/+page.markdoc @@ -0,0 +1,74 @@ +--- +layout: post +title: "Introducing generate command in the Appwrite CLI: Create a type-safe SDK from your schema" +description: Generate a type-safe SDK for your Appwrite project with the new generate command in the Appwrite CLI. It reads your database schema and creates typed helpers for querying and mutating rows with autocomplete. +date: 2026-02-06 +cover: /images/blog/appwrite-generate/cover.png +timeToRead: 5 +author: chirag-aggarwal +category: announcement +featured: false +callToAction: true +draft: false +--- + +Every database-driven app eventually ends up with the same glue code: types, table wrappers, and helper functions that make your schema feel safe to use in the editor. + +It starts small. Then your schema changes. A column gets renamed, a new required field appears, and suddenly the "simple" query you wrote last week is a runtime bug waiting to happen. + +To eliminate that drift, we're introducing the new `appwrite generate` command in the **Appwrite CLI**, which creates a **type-safe SDK tailored to your Appwrite project**. + +It reads your database schema and generates typed helpers, so you can interact with your tables using auto-completed methods with type checking built in. + +# One command. A project-aware SDK. + +Run the following command in your project directory: + +```sh +appwrite generate +``` + +The CLI automatically detects your project's language and generates your SDK into a `generated/appwrite/` directory. + +# Built for teams that ship fast + +The `appwrite generate` command is designed to keep your codebase and your schema in lockstep: + +- **Less boilerplate:** Stop hand-writing wrappers and types for every table. +- **Fewer runtime surprises:** Schema changes show up as type errors instead of production bugs. +- **Faster onboarding:** New teammates can discover what's available straight from the SDK. +- **Confident refactors:** Regenerate after schema updates and let the compiler tell you what needs attention. + +# Usage + +After generating the SDK, import it into your project and configure constants: + +```js +import { databases } from "./generated/appwrite/index.js"; +``` + +Configure your SDK constants by setting the values in `./generated/appwrite/constants.ts`. + +Then use the generated helpers to interact with your tables: + +```js +const mydb = databases.use("test-db"); +const customers = mydb.use("customers"); + +// Create a row +await customers.create({ + name: "Walter O' Brian", + email: "walter@example.com", + plan: "enterprise" +}); +``` + +Instead of juggling stringly-typed shapes, your editor can now guide you with autocomplete and validation based on the actual schema in your Appwrite project. + +# Available now + +The `appwrite generate` command is available today in the Appwrite CLI. + +To get started, head over to the [documentation](/docs/tooling/command-line/generate) and try it out in your next project. + +As always, we'd love to see what you build with it. diff --git a/src/routes/docs/tooling/command-line/+layout.svelte b/src/routes/docs/tooling/command-line/+layout.svelte index b756fb5452..274a16dfa8 100644 --- a/src/routes/docs/tooling/command-line/+layout.svelte +++ b/src/routes/docs/tooling/command-line/+layout.svelte @@ -22,6 +22,10 @@ { label: 'Non interactive', href: '/docs/tooling/command-line/non-interactive' + }, + { + label: 'Generate SDK', + href: '/docs/tooling/command-line/generate' } ] }, diff --git a/src/routes/docs/tooling/command-line/commands/+page.markdoc b/src/routes/docs/tooling/command-line/commands/+page.markdoc index 69fec699a9..5e4eb5daaa 100644 --- a/src/routes/docs/tooling/command-line/commands/+page.markdoc +++ b/src/routes/docs/tooling/command-line/commands/+page.markdoc @@ -39,6 +39,9 @@ Below is a list of the available commands in the Appwrite CLI. You can get more * `types [options] ` * The types command generates type definitions based on your Appwrite database schema. Learn more about [type generation](/docs/products/databases/type-generation). --- +* `generate` +* The generate command creates a type-safe SDK tailored to your project. It detects your project's language and generates typed helpers based on your database schema. Learn more about [SDK generation](/docs/tooling/command-line/generate). +--- {% /table %} ## Account commands {% #account-commands %} diff --git a/src/routes/docs/tooling/command-line/generate/+page.markdoc b/src/routes/docs/tooling/command-line/generate/+page.markdoc new file mode 100644 index 0000000000..a74e57380c --- /dev/null +++ b/src/routes/docs/tooling/command-line/generate/+page.markdoc @@ -0,0 +1,164 @@ +--- +layout: article +title: Generate SDK +description: Generate a type-safe SDK for your Appwrite project using the Command-Line Tool (CLI). Automatically create typed helpers based on your database schema. +--- + +{% partial file="cli-disclaimer.md" /%} + +The `generate` command creates a type-safe SDK tailored to your Appwrite project. It reads your database schema and generates typed helpers, so you can interact with your tables using auto-completed methods, resulting in a better developer experience. + +# Generate SDK {% #generate-sdk %} + +Run the following command in your project directory: + +```sh +appwrite generate +``` + +The CLI automatically detects your project's language and generates the SDK to a `generated/appwrite/` directory. + +# Options {% #options %} + +{% table %} +* Option +* Description +--- +* `-o, --output ` +* Output directory for generated files (default: `"generated"`) +--- +* `-l, --language ` +* Target language for SDK generation (supported: `typescript`) +--- +* `--server ` +* Override server-side generation (`auto`|`true`|`false`) (default: `"auto"`) +--- +* `-h, --help` +* Display help for command +--- +{% /table %} + +# Generated files {% #generated-files %} + +The generated SDK includes the following files: + +{% table %} +* File +* Description +--- +* `types.ts` +* Type definitions based on your database schema. +--- +* `databases.ts` +* Typed database helpers for querying and mutating rows. +--- +* `index.ts` +* Entry point that exports all generated helpers. +--- +* `constants.ts` +* Configuration constants such as your project endpoint and project ID. Update these values before using the SDK. +--- +{% /table %} + +# Usage {% #usage %} + +After generating the SDK, import it into your project: + +```js +import { databases } from "./generated/appwrite/index.js"; +``` + +Configure your SDK constants by setting the values in `./generated/appwrite/constants.ts`. + +Use the generated helpers to interact with your tables: + +```js +const customers = databases.use("main").use("customers"); + +const customer = await customers.create({ + name: "Walter O' Brian", + email: "walter@example.com" +}); +``` + +The generated helpers provide auto-completion and type checking based on your database schema, reducing errors and improving developer experience. + +# Examples {% #examples %} + +The generated SDK supports all common database operations. Below are examples across different use cases. + +## Get a row {% #get-row %} + +```js +const customer = await customers.get("customer-id-123"); +``` + +## List rows with queries {% #list-rows %} + +The `list` method accepts a typed query builder that provides auto-completion for your table's columns. + +```js +const results = await customers.list({ + queries: (q) => [ + q.equal("name", "Walter O' Brian"), + q.orderDesc("$createdAt"), + q.limit(10) + ] +}); +``` + +## Update a row {% #update-row %} + +```js +await customers.update("customer-id-123", { + email: "walter@scorpion.com" +}); +``` + +## Delete a row {% #delete-row %} + +```js +await customers.delete("customer-id-123"); +``` + +## Bulk operations {% #bulk-operations %} + +Create, update, or delete multiple rows at once. + +```js +await customers.createMany([ + { name: "Walter O' Brian", email: "walter@example.com" }, + { name: "Paige Dineen", email: "paige@example.com" } +]); +``` + +```js +await customers.updateMany( + { email: "updated@example.com" }, + { + queries: (q) => [q.equal("name", "Walter O' Brian")] + } +); +``` + +```js +await customers.deleteMany({ + queries: (q) => [q.equal("name", "Paige Dineen")] +}); +``` + +## Permissions {% #permissions %} + +Set row-level permissions when creating or updating rows. + +```js +await customers.create( + { name: "Walter O' Brian", email: "walter@example.com" }, + { + permissions: (permission, role) => [ + permission.read(role.any()), + permission.write(role.user("user-id-123")) + ] + } +); +``` diff --git a/static/images/blog/appwrite-generate/cover.png b/static/images/blog/appwrite-generate/cover.png new file mode 100644 index 0000000000..84434621ac Binary files /dev/null and b/static/images/blog/appwrite-generate/cover.png differ