{"id":18848412,"url":"https://github.com/pmbanugo/flargd","last_synced_at":"2025-04-14T08:21:21.457Z","repository":{"id":65613365,"uuid":"590967495","full_name":"pmbanugo/flargd","owner":"pmbanugo","description":"A fast \u0026 minimalist feature flag app that runs on Cloudflare Workers","archived":false,"fork":false,"pushed_at":"2024-01-04T06:04:53.000Z","size":68457,"stargazers_count":77,"open_issues_count":3,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-27T21:52:12.369Z","etag":null,"topics":["feature-flags","serverless","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pmbanugo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-01-19T16:22:57.000Z","updated_at":"2025-03-18T03:42:19.000Z","dependencies_parsed_at":"2023-11-13T11:45:04.599Z","dependency_job_id":null,"html_url":"https://github.com/pmbanugo/flargd","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmbanugo%2Fflargd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmbanugo%2Fflargd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmbanugo%2Fflargd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmbanugo%2Fflargd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmbanugo","download_url":"https://codeload.github.com/pmbanugo/flargd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248844036,"owners_count":21170505,"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":["feature-flags","serverless","typescript"],"created_at":"2024-11-08T03:12:28.361Z","updated_at":"2025-04-14T08:21:21.423Z","avatar_url":"https://github.com/pmbanugo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flargd - A fast, edge-based feature flag solution for modern applications 🏎\n\nFlargd is a feature flag application that you can use to implement feature toggling in your application. You can self-host it on Cloudflare Workers, and use it in your edge or serverless application (but not limited to these environments/runtimes).\n\n\u003e ⚠️ Flargd is currently in beta. Expect breaking changes prior to v1.0. You can follow my weekly update [publicly, on Twitter](https://twitter.com/p_mbanugo/status/1616467436919742465).\n\n![Speed test](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pxvkbt5d7h7rdyjc17rp.png)\n\n## Features 💰\n\n- **Fast** ⚡️ Less than 50ms RTT on average\n- **Minimal \u0026 Lightweight** 🧘🏽‍♀️ Minimalistic API that gets the job done\n- **Edge Runtime** ⚙️ Runs close to your users and application\n- **Self-hostable** 👩🏽‍💻\n- **Multi-project** support: You can configure feature flags for different applications you own\n- Admin UI\n- Web client/SDK \u003c [1Kb](https://bundlephobia.com/package/@flargd/web)\n- React Hooks and other framework integration (Coming soon)\n\n\u003e This project aims to be minimal, lightweight, fast, and easy to deploy and use on Edge and JavaScript runtimes. It's not meant to compete with other feature-flagging software in terms of features. Therefore, you'd likely use a different approach to achieve similar things with Flargd.\n\n## Self Hosting\n\nFlargd is built on Cloudflare Workers and KV. Follow these instructions to deploy to the Workers Platform:\n\n1. Clone this project.\n2. Run pnpm install at the project's root directory. _You can use any other package manager you choose_\n3. Create a [KV namespace](https://developers.cloudflare.com/workers/wrangler/workers-kv/#create-a-kv-namespace-with-wrangler) and update the `id` in **apps/api/wrangler.toml** for the `FLARGD_STORE` binding.\n4. Deploy the API in the **apps/api** directory using wrangler -- `wrangler publish` or `npx wrangler publish` from the _apps/api_ directory.\n5. Get the domain/URL for the workers you deployed in step 3. Copy it and replace the `CORE_API` variable value in **apps/admin-ui/wrangler.toml** with your Workers API domain.\n6. Deploy the admin UI located in the **apps/admin-ui** directory using wrangler.\n\n\u003e You can deploy with the [wrangler CLI](https://github.com/cloudflare/wrangler2) using the command `npx wrangler publish` (or `pnpm dlx wrangler publish`).\n\n## Quickstart\n\n\u003e This quickstart guide assumes you've already deployed your Flargd workers (API \u0026 UI) on Cloudflare Workers.\n\nThe first thing to do before using feature flags is to define them. You do that through the admin UI. To access the admin UI, open the URL to the deployed app in your browser. You should be presented with a page that looks like what you see below.\n\n![Flargd UI Console](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mya1ami6vumt62o61yea.png)\n\nYou should see an empty table if you're running the app for the first time. Otherwise, you'll see the list of flags and buttons to edit or delete them.\n\nTo create a feature flag, click the **Add Flag** button and the top left corner of the page. That should take you to the _create flag_ page. On this page, you can add a flag name and optionally a description. The percentage by default is set to `100`, and setting it to `0` disables the flag. The percentage value determines the ratio of users the flag should be enabled. The _Conditions_ section is optional and it allows you to apply rules to a flag. Each rule must pass for a flag to be evaluated as _active_.\n\n![Flargd - Create Page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bj0ixf9xn6362t9oxdp5.png)\n\nEnter the name `New_About_Page` for the flag and set the percentage to `70`. Click the **Save** but to save the flag. Follow the same steps to create flags for the following values with whatever percentage you like:\n\n- `New_Marketing_Page`\n- `New_Product_Page`\n\n### Using The Flags\n\nLet's make use of a basic A/B test Next.js application. You can clone the app from the [official examples repo](https://github.com/pmbanugo/flargd-examples/tree/main/edge-middleware/vercel-basic-ab-test-nextjs). After cloning, copy the `.env.example` file in this directory to `.env.local`:\n\n```bash\ncp .env.example .env.local\n```\n\nOpen `.env.local` and update `EDGE_FLAGS_HOST` to match the domain name for your _Flargd_ API.\n\nOpen the terminal and run `npm install` to install the dependencies. Included in the installed dependencies is the [@flargd/web](https://www.npmjs.com/package/@flargd/web) npm package which is used by web clients/apps to access the feature flags.\n\nIt provides two methods to retrieve flags using the `get()` and `getMany()` functions. You can see the usage in the **lib/api.ts** file. The `getFeatureFlagVariant()` function first instantiates the client using the `createClient()` function, then it calls `client.get(featureName)` to retrieve the flag.\n\n```typescript\nexport async function getFeatureFlagVariant(\n  featureName: Flags,\n  distinctUserId: string\n): Promise\u003cFlagValue\u003e {\n  if (!distinctUserId) {\n    throw new Error(`distinctUserId is required and it can't be empty`);\n  }\n\n  const client = createClient({\n    host: EDGE_FLAGS_HOST,\n    app: EDGE_FLAGS_APP,\n    distinctId: distinctUserId,\n  });\n\n  const flag = await client.get(featureName);\n\n  return flag.enable;\n}\n```\n\nThe `getFeatureFlagVariant()` function is used in **middleware.ts** at the root of the project. This is where the feature flag is retrieved and the middleware decides where to redirect the user based on the result. When deployed on Vercel, the middleware executes before a request is processed on a site, to provide speed and personalization to your users!\n\n\u003e This is where Flargd shines! 🌟 Your Edge Middleware or Functions, together with your feature flags, runs close to the user, with reduced latency. They run at the same location as your edge functions (Vercel Edge Functions/Middleware, Cloudflare Workers, etc), giving your application an increased speed 🏎⚡️\n\nStart the Next.js application using the command `npm run dev`. Open it in your browser and follow the UI prompt. You can click the **reset** button to reset the feature flag values.\n\nThere you have your first application using Flargd 👏🏽\n\nFor more examples, check out [github.com/pmbanugo/flargd-examples](https://github.com/pmbanugo/flargd-examples).\n\nFor more description about the @flargd/web SDK, check its [documentation](/packages/web/README.md)\n\n## Examples\n\nYou'll find most of the examples in [github.com/pmbanugo/flargd-examples](https://github.com/pmbanugo/flargd-examples). Here are a few examples:\n\n- [Vercel Edge Middleware](https://github.com/pmbanugo/flargd-examples/tree/main/edge-functions/vercel-edge-middleware-nextjs): This example shows how to do A/B testing at the edge with Vercel Edge Middleware and Flargd.\n\nThere'll be more examples in the near future 👨🏽‍💻\n\n## Admin UI\n\n### Conditions\n\nConditions are a way to apply rules to the flags. A condition consists of an **attribute**, **condition**, and a set of **values/target**. The attributes include:\n\n1. City: The city of the originating request, for example, `\"Munich\"`.\n1. Country: The two-letter country [code (in ISO 3166-1 Alpha 2 format)](https://www.iso.org/obp/ui/#search/code/) of the user/client. E.g `DE` for Germany.\n1. Continent: The continent of the incoming user/client request. This is represented by the continent code such as:\n   - AF: Africa\n   - AN: Antarctica\n   - AS: Asia\n   - EU: Europe\n   - NA: North America\n   - OC: Oceania\n   - SA: South America\n   - T1: Tor network\n1. Postal Code: The postal code associated with the user/client request.\n1. Region: The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) name for the first level region associated with the user/client request, for example, `\"Texas\"`.\n1. IP: The IP of the user/client.\n\nThe _condition_ is a way to compare the values in the request, to the values defined for the flag. The _target_ contains the values to compare with the incoming client request. You can add multiple values, separated by a comma.\n\n## Contributing\n\nSee the [contribution guide](/CONTRIBUTING.md)\n\n## Roadmap 🚧\n\nComing soon 🔜\n\n## Author\n\nThis project is created by [Peter Mbanugo](https://github.com/pmbanugo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmbanugo%2Fflargd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmbanugo%2Fflargd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmbanugo%2Fflargd/lists"}