From b79304b676c7abc0e9c5eff330fb7a1f8d937dfd Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 14 Mar 2025 13:45:40 +0100 Subject: [PATCH 1/5] docs --- README.md | 17 ++++++----- packages/react-sdk/README.md | 55 +++++++++++++++++++++--------------- 2 files changed, 43 insertions(+), 29 deletions(-) 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/react-sdk/README.md b/packages/react-sdk/README.md index c646943a..efda8754 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 `npm 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 +❯ npm 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: From ca84bbecf0fa8c5643540c16efce4d3c06654498 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 14 Mar 2025 14:03:11 +0100 Subject: [PATCH 2/5] add node.js docs --- packages/node-sdk/README.md | 46 ++++++++++++++---------------------- packages/react-sdk/README.md | 4 ++-- 2 files changed, 20 insertions(+), 30 deletions(-) diff --git a/packages/node-sdk/README.md b/packages/node-sdk/README.md index 9d9fd6d8..1b0681f4 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: + +``` +npm run 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 efda8754..4152c3b9 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -43,11 +43,11 @@ Install the Bucket CLI: npm i --save-dev @bucketco/cli ``` -Run `npm bucket new` to create your first feature! +Run `npm run 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 -❯ npm bucket new +❯ npm run bucket new Opened web browser to facilitate login: https://app.bucket.co/api/oauth/cli/authorize Welcome to Bucket! From bf96bdd4afca8f160010325c25887dc33ae16c1b Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 14 Mar 2025 14:14:21 +0100 Subject: [PATCH 3/5] let users know how they can see available apps --- packages/cli/utils/errors.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; } From 98b346cf04c0fe874cc74881d8a1f22eae6acdfd Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 14 Mar 2025 14:57:37 +0100 Subject: [PATCH 4/5] use `npx` --- packages/node-sdk/README.md | 2 +- packages/react-sdk/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/node-sdk/README.md b/packages/node-sdk/README.md index 1b0681f4..1e289289 100644 --- a/packages/node-sdk/README.md +++ b/packages/node-sdk/README.md @@ -315,7 +315,7 @@ npm i --save-dev @bucketco/cli then generate the types: ``` -npm run bucket features types +npx bucket features types ``` This will generate a `bucket.d.ts` containing all your features. diff --git a/packages/react-sdk/README.md b/packages/react-sdk/README.md index 4152c3b9..8e2f65b3 100644 --- a/packages/react-sdk/README.md +++ b/packages/react-sdk/README.md @@ -43,11 +43,11 @@ Install the Bucket CLI: npm i --save-dev @bucketco/cli ``` -Run `npm run bucket new` to create your first feature! +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 -❯ npm run bucket new +❯ npx bucket new Opened web browser to facilitate login: https://app.bucket.co/api/oauth/cli/authorize Welcome to Bucket! From e1971eb6f746ae4fe1e4456accecd8ba7d6373f0 Mon Sep 17 00:00:00 2001 From: Ron Cohen Date: Fri, 14 Mar 2025 15:04:08 +0100 Subject: [PATCH 5/5] adding the CLI --- typedoc.json | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/typedoc.json b/typedoc.json index efc70f7e..c12353a8 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,7 +1,11 @@ { "$schema": "https://typedoc-plugin-markdown.org/schema.json", - "plugin": ["typedoc-plugin-markdown", "typedoc-plugin-frontmatter", "typedoc-plugin-mdn-links"], + "plugin": [ + "typedoc-plugin-markdown", + "typedoc-plugin-frontmatter", + "typedoc-plugin-mdn-links" + ], "entryPointStrategy": "packages", "entryPoints": [ @@ -12,14 +16,17 @@ "packageOptions": { "entryPoints": ["src/index.ts"] }, - "projectDocuments": ["packages/browser-sdk/FEEDBACK.md"], + "projectDocuments": [ + "packages/browser-sdk/FEEDBACK.md", + "packages/cli/README.md" + ], "readme": "none", "useHTMLAnchors": false, "outputs": [ { "name": "markdown", - "path": "./dist/docs", + "path": "./dist/docs" } ], "outputFileStrategy": "modules", @@ -31,7 +38,7 @@ "includeFolders": false, "excludeReferences": true }, - + "disableSources": true, "categorizeByGroup": false, "groupReferencesByType": true, @@ -40,7 +47,7 @@ "expandObjects": true, "expandParameters": true, "typeDeclarationVisibility": "verbose", - + "indexFormat": "htmlTable", "parametersFormat": "htmlTable", "interfacePropertiesFormat": "htmlTable", @@ -54,7 +61,7 @@ "hideBreadcrumbs": true, "hidePageTitle": false, "hidePageHeader": true, - + "tableColumnSettings": { "hideDefaults": false, "hideInherited": true, @@ -67,22 +74,22 @@ "frontmatterGlobals": { "layout": { - "visible": true, + "visible": true }, "title": { - "visible": true, + "visible": true }, "description": { - "visible": false, + "visible": false }, "tableOfContents": { - "visible": true, + "visible": true }, "outline": { - "visible": true, + "visible": true }, "pagination": { - "visible": true, + "visible": true } } }