diff --git a/README.md b/README.md index 2f049086..8ae875a9 100644 --- a/README.md +++ b/README.md @@ -4,26 +4,30 @@ Bucket is B2B feature flagging with a built-in feedback loop that lets you roll [Learn more and get started](https://bucket.co/) -## SDKs - -### React SDK +## React SDK Client side React SDK [Read the docs](packages/react-sdk/README.md) -### Browser SDK +## Browser SDK Browser SDK for use in non-React web applications -[Read the docs](packages/browser-sdk/README.md) +[Read the docs](packages/browser-sdk/README.md) -### Node.js SDK +## Node.js SDK Node.js SDK for use on the server side. [Read the docs](packages/node-sdk/README.md) +## Bucket CLI + +CLI to interact with Bucket and generate types + +[Read the docs](packages/cli/README.md) + ## OpenFeature Browser Provider Use Bucket with OpenFeature in the browser through the Bucket OpenFeature Browser Provider @@ -36,7 +40,6 @@ Use the Bucket with OpenFeature on the server in Node.js through the Bucket Open [Read the docs](packages/openfeature-node-provider/README.md) - ## Development ### Versioning diff --git a/packages/cli/utils/errors.ts b/packages/cli/utils/errors.ts index c0df8ce2..e7b9340e 100644 --- a/packages/cli/utils/errors.ts +++ b/packages/cli/utils/errors.ts @@ -5,7 +5,7 @@ import chalk from "chalk"; export class MissingAppIdError extends Error { constructor() { super( - "App ID is required. Please provide it with --appId or in the config file.", + "App ID is required. Please provide it with --appId or in the config file. Use `bucket apps list` to see available apps.", ); this.name = "MissingAppIdError"; } diff --git a/packages/node-sdk/README.md b/packages/node-sdk/README.md index 9d9fd6d8..1e289289 100644 --- a/packages/node-sdk/README.md +++ b/packages/node-sdk/README.md @@ -306,38 +306,26 @@ order of importance: ## Type safe feature flags -To get type checked feature flags, add the list of flags to your `bucket.ts` file. -Any feature look ups will now be checked against the list you maintain. +To get type checked feature flags, install the Bucket CLI: + +``` +npm i --save-dev @bucketco/cli +``` + +then generate the types: + +``` +npx bucket features types +``` + +This will generate a `bucket.d.ts` containing all your features. +Any feature look ups will now be checked against the features that exist in Bucket. + +Here's an example of a failed type check: ```typescript import { BucketClient } from "@bucketco/node-sdk"; -// Extending the Features interface to define the available features -declare module "@bucketco/node-sdk" { - interface Features { - "show-todos": boolean; - "create-todos": { - isEnabled: boolean; - config: { - key: string; - payload: { - minimumLength: number; - }; - }; - }; - "delete-todos": { - isEnabled: boolean; - config: { - key: string; - payload: { - requireConfirmation: boolean; - maxDeletionsPerDay: number; - }; - }; - }; - } -} - export const bucketClient = new BucketClient(); bucketClient.initialize().then(() => { @@ -355,6 +343,8 @@ bucketClient.initialize().then(() => { ![Type check failed](docs/type-check-failed.png "Type check failed") +This is an example of a failed config payload check: + ```typescript bucketClient.initialize().then(() => { // TypeScript will catch this error as well: "minLength" is not part of the payload. diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index c646943a..8e2f65b3 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -16,28 +16,7 @@ npm i @bucketco/react-sdk ## Get started -### 1. Define Features (optional) - -To get type safe feature definitions, extend the definition of the `Features` interface and define which features you have. -See the example below for the details. - -If no explicit feature definitions are provided, there will be no types checked feature lookups. - -**Example:** - -```typescript -import "@bucketco/react-sdk"; - -// Define your features by extending the `Features` interface in @bucketco/react-sdk -declare module "@bucketco/react-sdk" { - interface Features { - huddle: boolean; - recordVideo: boolean; - } -} -``` - -### 2. Add the `BucketProvider` context provider +### 1. Add the `BucketProvider` context provider Add the `BucketProvider` context provider to your application: @@ -56,6 +35,38 @@ import { BucketProvider } from "@bucketco/react-sdk"; ; ``` +### 2. Create a new feature and set up type safety + +Install the Bucket CLI: + +```shell +npm i --save-dev @bucketco/cli +``` + +Run `npx bucket new` to create your first feature! +On the first run, it will sign into Bucket and set up type generation for your project: + +```shell +❯ npx bucket new +Opened web browser to facilitate login: https://app.bucket.co/api/oauth/cli/authorize + +Welcome to Bucket! + +? Where should we generate the types? gen/features.d.ts +? What is the output format? react +✔ Configuration created at bucket.config.json. + +Creating feature for app Slick app. +? New feature name: Huddle +? New feature key: huddle +✔ Created feature Huddle with key huddle (https://app.bucket.co/features/huddles) +✔ Generated react types in gen/features.d.ts. +``` + +> [!Note] +> By default, types will be generated in `gen/features.d.ts`. +> The default `tsconfig.json` file `include`s this file by default, but if your `tsconfig.json` is different, make sure the file is covered in the `include` property. + ### 3. Use `useFeature()` to get feature status Using the `useFeature` hook from your components lets you toggle features on/off and track feature usage: