This repository contains various packages and apps related consuming Cloudflare's AI offerings on the client-side. It is a monorepo powered by Nx and Changesets.
- demos [Apps that demonstrate Cloudflare AI capabilities]
- libs [Shared libraries for demos and packages]
- packages [Packages that can be published to npm]
workers-ai-provider: A custom provider that enables Workers AI's models for the Vercel AI SDK.
-
Clone the repository.
git clone git@github.com:cloudflare/ai.git
-
Install Dependencies.
From the root directory, run:
cd ai npm install -
Develop.
To start a development server for a specific app (for instance,
tool-calling):npx nx dev tool-calling
Ideally all commands should be executed from the repository root with the
npx nxprefix. This will ensure that the dependency graph is managed correctly, e.g. if one package relies on the output of an other. -
Testing and Linting.
-
To execute your continuous integration tests for a specific project (e.g.,
workers-ai-provider):npx nx test:ci workers-ai-provider
-
To lint a specific project:
npx nx lint my-project
-
To run a more comprehensive sweep of tasks (lint, tests, type checks, build) against one or more projects:
npx nx run-many -t lint test:ci type-check build -p "my-project other-project"
- Other Nx Tasks.
build: Compiles a project or a set of projects.test: Runs project tests in watch mode.test:ci: Runs tests in CI mode (no watch).test:smoke: Runs smoke tests.type-check: Performs TypeScript type checks.
We appreciate contributions and encourage pull requests. Please follow these guidelines:
- Project Setup: After forking or cloning, install dependencies with
npm install. - Branching: Create a new branch for your feature or fix.
- Making Changes:
- Add or update relevant tests.
- On pushing your changes, automated tasks will be run (courtesy of a Husky pre-push hook).
- Changesets: If your changes affect a published package, run
npx changesetto create a changeset. Provide a concise summary of your changes in the changeset prompt. - Pull Request: Submit a pull request to the
mainbranch. The team will review it and merge if everything is in order.
This repository uses Changesets to manage versioning and publication:
-
Changeset Creation: Whenever a change is made that warrants a new release (e.g., bug fixes, new features), run:
npx changeset
Provide a clear description of the changes.
-
Merging: Once the changeset is merged into
main, our GitHub Actions workflows will:
- Detect the changed packages, and create a Version Packages PR.
- Increment versions automatically (via Changesets).
- Publish any package that has a version number to npm. (Demos and other internal items do not require versioning.)
- Publication: The release workflow (
.github/workflows/release.yml) will run on every push tomain. It ensures each published package is tagged and released on npm. Any package with a version field in itspackage.jsonwill be included in this process.
In this monorepo, we rely on hoisting to place common dependencies in the root node_modules, thereby simplifying version management. This practice means:
- Shared dependencies appear only once at the root.
- Individual package or library directories usually contain only project-specific dependencies.
Should you encounter version conflicts or require specific dependency versions, adjustments can be made on a per-package basis, but in general, we keep everything consolidated at the root wherever possible.
In this monorepo, relative paths are used for imports in order to simplify the tool-chain. This means that when you import a module, you should use the relative path from the file where you're importing it. For example:
import { myFunction } from '../my-package/src/myFunction';There are several tsconfig files at the root that cover the various environments that each package or file is supposed to run in. In most cases, this means that you don't need a tsconfig in each package, but sometimes it's unavoidable, especially in published packages.
The way that it is setup, each file by default is included in the tsconfig.node.json config. So this will apply to everything in the package. If the src for the package is not supposed to run in Node, then you can add it to the relevant tsconfig. For example:
- my-browser-based-app
- src
- index.ts
some-node-config-or-script.ts
package.jsonHere, the some-node-config-or-script.ts file falls correctly under the tsconfig.node.json config, but we can add the src folder to the tsconfig.browser.json config.
For any queries or guidance, kindly open an issue or submit a pull request. We hope this structure and process help you to contribute effectively.
{ "extends": "./tsconfig.base.json", "compilerOptions": { ... }, "include": [ "./demos/my-browser-based-app/src/client/**/*.ts", "./demos/my-browser-based-app/src/client/**/*.tsx", ] }