{"id":18853035,"url":"https://github.com/featbit/featbit-node-server-sdk","last_synced_at":"2025-04-14T10:23:02.637Z","repository":{"id":207597230,"uuid":"719635955","full_name":"featbit/featbit-node-server-sdk","owner":"featbit","description":"FeatBit Server-Side SDK for Node.js","archived":false,"fork":false,"pushed_at":"2025-03-17T11:33:37.000Z","size":354,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T23:41:43.739Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://featbit.co","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/featbit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-16T15:30:00.000Z","updated_at":"2025-03-17T11:33:40.000Z","dependencies_parsed_at":"2023-11-16T16:52:04.141Z","dependency_job_id":"6400ded1-db62-48ac-8a0f-372b1e074eea","html_url":"https://github.com/featbit/featbit-node-server-sdk","commit_stats":null,"previous_names":["featbit/featbit-node-server-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/featbit%2Ffeatbit-node-server-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/featbit%2Ffeatbit-node-server-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/featbit%2Ffeatbit-node-server-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/featbit%2Ffeatbit-node-server-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/featbit","download_url":"https://codeload.github.com/featbit/featbit-node-server-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860324,"owners_count":21173407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T03:42:43.571Z","updated_at":"2025-04-14T10:23:02.597Z","avatar_url":"https://github.com/featbit.png","language":"TypeScript","readme":"# FeatBit Server-Side SDK for Node.js\n\n## Introduction\n\nThis is the Node.js Server-Side SDK for the 100% open-source feature flags management platform [FeatBit](https://github.com/featbit/featbit).\n\nThe FeatBit Server-Side SDK for Node.js is designed primarily for use in multi-user systems such as web servers and applications. It is not intended for use in desktop and embedded systems applications.\n\n## Data synchronization\nWe use **WebSocket** or **Polling** to make the local data synchronized with the server, and then store them in memory by default. Whenever there is any change to a feature flag or its related data, this change will be pushed to the SDK, the average synchronization time is less than **100ms**. Be aware the WebSocket/Polling connection may be interrupted due to internet outage, but it will be resumed automatically once the problem is gone.\n\n## Get Started\n\n### Installation\nThe latest stable version is available on [npm](https://www.npmjs.com/package/@featbit/node-server-sdk).\n\n```bash\nnpm install --save @featbit/node-server-sdk\n```\n### Prerequisite\n\nBefore using the SDK, you need to obtain the environment secret (the sdkKey) and SDK URLs.\n\nFollow the documentation below to retrieve these values\n- [How to get environment secret](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret)\n- [How to get SDK URLs](https://docs.featbit.co/sdk/faq#how-to-get-the-sdk-urls)\n\n### Quick Start\n\nThe following code demonstrates the basic usage of `@featbit/node-server-sdk`.\n\n```javascript\nimport { FbClientBuilder } from \"@featbit/node-server-sdk\";\n\n// setup SDK options\nconst fbClient = new FbClientBuilder()\n    .sdkKey(\"your_sdk_key\")\n    .streamingUri('ws://localhost:5100')\n    .eventsUri(\"http://localhost:5100\")\n    .build();\n\n(async () =\u003e {\n  // wait for the SDK to be initialized\n  try {\n    await fbClient.waitForInitialization();\n  } catch(err) {\n    // failed to initialize the SDK\n    console.log(err);\n  }\n\n  // flag to be evaluated\n  const flagKey = \"game-runner\";\n  \n  // create a user\n  const user = new UserBuilder('a-unique-key-of-user')\n    .name('bob')\n    .custom('sex', 'female')\n    .custom('age', 18)\n    .build();\n\n  // evaluate a feature flag for a given user\n  const boolVariation = await fbClient.boolVariation(flagKey, user, false);\n  console.log(`flag '${flagKey}' returns ${boolVariation} for user ${user.Key}`);\n\n  // evaluate a boolean flag for a given user with evaluation detail\n  const boolVariationDetail = await fbClient.boolVariationDetail(flagKey, user, false);\n  console.log(`flag '${flagKey}' returns ${boolVariationDetail.value} for user ${user.Key}` +\n  `Reason Kind: ${boolVariationDetail.kind}, Reason Description: ${boolVariationDetail.reason}`);\n\n  // make sure the events are flushed before exit\n  await fbClient.close();\n})();\n```\n\n## Examples\n- [Console App](./examples/console-app)\n\n## SDK\n\n### FbClientNode\n\nThe `FbClientNode` is the heart of the SDK which provides access to FeatBit server. Applications should instantiate a single instance for the lifetime of the application.\n\n`FbClientBuilder` is used to construct a `FbClientNode` instance. The builder exposes methods to configure the SDK, and finally to create the `FbClientNode` instance.\n\n#### FbClient Using Streaming\n\n```javascript\nimport { FbClientBuilder } from \"@featbit/node-server-sdk\";\n\nconst fbClient = new FbClientBuilder()\n    .sdkKey(\"your_sdk_key\")\n    .streamingUri('ws://localhost:5100')\n    .eventsUri(\"http://localhost:5100\")\n    .build();\n```\n#### FbClient Using Polling\n\n```javascript\nimport { FbClientBuilder, DateSyncMode } from \"@featbit/node-server-sdk\";\n\nconst fbClient = new FbClientBuilder()\n    .sdkKey(\"your_sdk_key\")\n    .dataSyncMode(DateSyncMode.POLLING)\n    .pollingUri('http://localhost:5100')\n    .eventsUri(\"http://localhost:5100\")\n    .pollingInterval(10000)\n    .build();\n```\n\n#### IUser\n\nIUser defines the attributes of a user for whom you are evaluating feature flags. IUser has two built-in attributes: key and name. The only mandatory attribute of a IUser is the key, which must uniquely identify each user.\n\nBesides these built-in properties, you can define any additional attributes associated with the user using `custom(string key, string value)` method on UserBuilder. Both built-in attributes and custom attributes can be referenced in targeting rules, and are included in analytics data.\n\nUserBuilder is used to construct a `IUser` instance. The builder exposes methods to configure the IUser, and finally to create the IUser instance.\n\n```javascript\nimport { UserBuilder } from \"@featbit/node-server-sdk\";\n\nconst bob = new UserBuilder(\"unique_key_for_bob\")\n    .name(\"Bob\")\n    .custom('age', 18)\n    .custom('country', 'FR')\n    .build();\n```\n\n### Evaluating flags\n\nBy using the feature flag data it has already received, the SDK **locally calculates** the value of a feature flag for a\ngiven user.\n\nThere is a `variation` method that returns a flag value, and a `variationDetail` method that returns an object\ndescribing how the value was determined for each type.\n\n- boolVariation/boolVariationDetail\n- stringVariation/stringVariationDetail\n- numberVariation/numberVariationDetail\n- jsonVariation/jsonVariationDetail\n\nVariation calls take the feature flag key, a IUser, and a default value. If any error makes it impossible to\nevaluate the flag (for instance, the feature flag key does not match any existing flag), default value is returned.\n\n```javascript\n// flag to be evaluated\nconst flagKey = \"game-runner\";\n\n// create a user\nconst user = new UserBuilder('a-unique-key-of-user')\n    .name('bob')\n    .custom('sex', 'female')\n    .custom('age', 18)\n    .build();\n\n// evaluate a feature flag for a given user\nconst boolVariation = await fbClient.boolVariation(flagKey, user, false);\nconsole.log(`flag '${flagKey}' returns ${boolVariation} for user ${user.Key}`);\n\n// evaluate a boolean flag for a given user with evaluation detail\nconst boolVariationDetail = await fbClient.boolVariationDetail(flagKey, user, false);\nconsole.log(`flag '${flagKey}' returns ${boolVariationDetail.value} for user ${user.Key}` +\n    `Reason Kind: ${boolVariationDetail.kind}, Reason Description: ${boolVariationDetail.reason}`);\n```\n\n### Offline Mode\n\nIn some situations, you might want to stop making remote calls to FeatBit. Here is how:\n```javascript\nimport { FbClientBuilder } from \"@featbit/node-server-sdk\";\n\nconst fbClient = new FbClientBuilder()\n    .offline(true)\n    .build();\n\n```\n\n\u003e **_NOTE:_** Populating data from a JSON string is only supported in offline mode.\n\nThe format of the data in flags and segments is defined by FeatBit and is subject to change. Rather than trying to\nconstruct these objects yourself, it's simpler to request existing flags directly from the FeatBit server in JSON format\nand use this output as the starting point for your file. Here's how:\n\n```shell\n# replace http://localhost:5100 with your evaluation server url\ncurl -H \"Authorization: \u003cyour-env-secret\u003e\" http://localhost:5100/api/public/sdk/server/latest-all \u003e featbit-bootstrap.json\n```\n\nThen use that file to initialize FbClient:\n```javascript\nimport { FbClientBuilder } from \"@featbit/node-server-sdk\";\nimport fs from 'fs';\n\nlet data: string = '';\ntry {\n  data = fs.readFileSync('path_to_the_json_file', 'utf8');\n} catch (err) {\n  console.error(err);\n}\n\nconst fbClient = new FbClientBuilder()\n    .offline(false)\n    .useJsonBootstrapProvider(data)\n    .build();\n```\n\n### Experiments (A/B/n Testing)\n\nWe support automatic experiments for pageviews and clicks, you just need to set your experiment on our SaaS platform,\nthen you should be able to see the result in near real time after the experiment is started.\n\nIn case you need more control over the experiment data sent to our server, we offer a method to send custom event.\n\n```javascript\nfbClient.track(user, eventName, numericValue);\n```\n\n**numericValue** is not mandatory, the default value is **1.0**.\n\nMake sure `track` is called after the related feature flag is called, otherwise the custom event won't be included\ninto the experiment result.\n\n## Supported Node.js versions\n\nThis version of the SDK should work for the recent versions of Node.js, if you see any issues with a specific version,\nplease create an issue.\n\n## Getting support\n- If you have a specific question about using this sdk, we encourage you\n  to [ask it in our slack](https://join.slack.com/t/featbit/shared_invite/zt-1ew5e2vbb-x6Apan1xZOaYMnFzqZkGNQ).\n- If you encounter a bug or would like to request a\n  feature, [submit an issue](https://github.com/featbit/dotnet-server-sdk/issues/new).\n\n## See Also\n- [Connect To Node.js Sdk](https://docs.featbit.co/getting-started/connect-an-sdk#node.js)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeatbit%2Ffeatbit-node-server-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffeatbit%2Ffeatbit-node-server-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeatbit%2Ffeatbit-node-server-sdk/lists"}