diff --git a/package.json b/package.json index b7b0bdc24b..bf8d609aef 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "packages/sdk/react-universal/example", "packages/sdk/vercel", "packages/sdk/svelte", + "packages/sdk/svelte/example", "packages/sdk/akamai-base", "packages/sdk/akamai-base/example", "packages/sdk/akamai-edgekv", diff --git a/packages/sdk/svelte/README.md b/packages/sdk/svelte/README.md new file mode 100644 index 0000000000..c8d7def68e --- /dev/null +++ b/packages/sdk/svelte/README.md @@ -0,0 +1,131 @@ +# Launch Darkly Svelte SDK + +This is a Svelte library for Launch Darkly. It is a wrapper around the official Launch Darkly JavaScript SDK but with a Svelte-friendly API. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Advanced Usage](#advanced-usage) + - [Changing user context](#changing-user-context) + - [Getting feature flag values](#getting-feature-flag-values) + - [Getting immediate flag value](#getting-immediate-flag-value) + - [Watching flag value changes](#watching-flag-value-changes) + - [Getting all flag values](#getting-all-flag-values) + +## Getting started + +First, install the package: + +```bash +npm install @launchdarkly/svelte-client-sdk # or use yarn or pnpm +``` + +Then, initialize the SDK with your client-side ID using the `LDProvider` component: + +```svelte + + +// Use context relevant to your application +const context = { + user: { + key: 'user-key', + }, +}; + + + + +``` + +Now you can use the `LDFlag` component to conditionally render content based on feature flags: + +```svelte + + + +
+

this will render if the feature flag is on

+
+
+

this will render if the feature flag is off

+
+
+``` + +## Advanced usage + +### Changing user context + +You can change the user context by using the `identify` function from the `LD` object: + +```svelte + + + +``` + +### Getting feature flag values + +#### Getting immediate flag value + +If you need to get the value of a flag at time of evaluation you can use the `useFlag` function: + +```svelte + + + +``` + +**Note:** Please note that `useFlag` function will return the current value of the flag at the time of evaluation, which means you won't get notified if the flag value changes. This is useful for cases where you need to get the value of a flag at a specific time like a function call. If you need to get notified when the flag value changes, you should use the `LDFlag` component, the `watch` function or the `flags` object depending on your use case. + +#### Watching flag value changes + +If you need to get notified when a flag value changes you can use the `watch` function. The `watch` function is an instance of [Svelte Store](https://svelte.dev/docs/svelte-store), which means you can use it with the `$` store subscriber syntax or the `subscribe` method. Here is an example of how to use the `watch` function: + +```svelte + + +

{$flagValue}

+``` + +#### Getting all flag values + +If you need to get all flag values you can use the `flags` object. The `flags` object is an instance of [Svelte Store](https://svelte.dev/docs/svelte-store), which means you can use it with the `$` store subscriber syntax or the `subscribe` method. Here is an example of how to use the `flags` object: + +```svelte + + +{#each Object.keys($allFlags) as flagName} +

{flagName}: {$allFlags[flagName]}

+{/each} +``` + +## Credits + +- Original code by [Robinson Marquez](https://github.com/nosnibor89) \ No newline at end of file diff --git a/packages/sdk/svelte/example/.eslintignore b/packages/sdk/svelte/example/.eslintignore new file mode 100644 index 0000000000..38972655fa --- /dev/null +++ b/packages/sdk/svelte/example/.eslintignore @@ -0,0 +1,13 @@ +.DS_Store +node_modules +/build +/.svelte-kit +/package +.env +.env.* +!.env.example + +# Ignore files for PNPM, NPM and YARN +pnpm-lock.yaml +package-lock.json +yarn.lock diff --git a/packages/sdk/svelte/example/.eslintrc.cjs b/packages/sdk/svelte/example/.eslintrc.cjs new file mode 100644 index 0000000000..0b757582c0 --- /dev/null +++ b/packages/sdk/svelte/example/.eslintrc.cjs @@ -0,0 +1,31 @@ +/** @type { import("eslint").Linter.Config } */ +module.exports = { + root: true, + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/recommended', + 'plugin:svelte/recommended', + 'prettier' + ], + parser: '@typescript-eslint/parser', + plugins: ['@typescript-eslint'], + parserOptions: { + sourceType: 'module', + ecmaVersion: 2020, + extraFileExtensions: ['.svelte'] + }, + env: { + browser: true, + es2017: true, + node: true + }, + overrides: [ + { + files: ['*.svelte'], + parser: 'svelte-eslint-parser', + parserOptions: { + parser: '@typescript-eslint/parser' + } + } + ] +}; diff --git a/packages/sdk/svelte/example/.gitignore b/packages/sdk/svelte/example/.gitignore new file mode 100644 index 0000000000..ac7211b403 --- /dev/null +++ b/packages/sdk/svelte/example/.gitignore @@ -0,0 +1,11 @@ +.DS_Store +node_modules +/build +/dist +/.svelte-kit +/package +.env +.env.* +!.env.example +vite.config.js.timestamp-* +vite.config.ts.timestamp-* diff --git a/packages/sdk/svelte/example/.npmrc b/packages/sdk/svelte/example/.npmrc new file mode 100644 index 0000000000..b6f27f1359 --- /dev/null +++ b/packages/sdk/svelte/example/.npmrc @@ -0,0 +1 @@ +engine-strict=true diff --git a/packages/sdk/svelte/example/.prettierignore b/packages/sdk/svelte/example/.prettierignore new file mode 100644 index 0000000000..cc41cea9b2 --- /dev/null +++ b/packages/sdk/svelte/example/.prettierignore @@ -0,0 +1,4 @@ +# Ignore files for PNPM, NPM and YARN +pnpm-lock.yaml +package-lock.json +yarn.lock diff --git a/packages/sdk/svelte/example/.prettierrc b/packages/sdk/svelte/example/.prettierrc new file mode 100644 index 0000000000..95730232b6 --- /dev/null +++ b/packages/sdk/svelte/example/.prettierrc @@ -0,0 +1,8 @@ +{ + "useTabs": true, + "singleQuote": true, + "trailingComma": "none", + "printWidth": 100, + "plugins": ["prettier-plugin-svelte"], + "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }] +} diff --git a/packages/sdk/svelte/example/README.md b/packages/sdk/svelte/example/README.md new file mode 100644 index 0000000000..173a3cb6c8 --- /dev/null +++ b/packages/sdk/svelte/example/README.md @@ -0,0 +1,36 @@ +# LaunchDarkly Svelte SDK Example + +This project demonstrates the usage of the `@launchdarkly/svelte-client-sdk`. It showcases how to conditionally render content based on feature flags using the `LDFlag` component. + +## Installing Dependencies and Setting Environment Variables + +First, install the project dependencies: + +```bash +yarn install +``` + +Next, create a `.env` file in the root of the project and add your LaunchDarkly client-side ID and flag key. You can obtain these from any LaunchDarkly project/environment you choose. + +```bash +PUBLIC_LD_CLIENT_ID=your-client-side-id +PUBLIC_LD_FLAG_KEY=your-flag-key +``` + +Note: The flag specified by `PUBLIC_LD_FLAG_KEY` must be a boolean flag. + +## Running the Project + +To run the project, use the following command: + +```bash +yarn dev +``` + +This will start the development server. Open your browser and navigate to the provided URL to see the example in action. The box will change its background color based on the value of the feature flag specified by `PUBLIC_LD_FLAG_KEY`. + +### Role of `LDProvider` + +The `LDProvider` component is used to initialize the LaunchDarkly client and provide the feature flag context to the rest of the application. It requires a `clientID` and a `context` object. The `context` object typically contains information about the user or environment, which LaunchDarkly uses to determine the state of feature flags. + +In this example, the `LDProvider` wraps the entire application, ensuring that all child components have access to the feature flag data. The `slot="initializing"` is used to display a loading message while the flags are being fetched. diff --git a/packages/sdk/svelte/example/package.json b/packages/sdk/svelte/example/package.json new file mode 100644 index 0000000000..7d0b084570 --- /dev/null +++ b/packages/sdk/svelte/example/package.json @@ -0,0 +1,49 @@ +{ + "name": "ld-svelte-example", + "version": "0.0.1", + "scripts": { + "dev": "vite dev", + "build": "vite build", + "preview": "vite preview" + }, + "exports": { + ".": { + "types": "./dist/index.d.ts", + "svelte": "./dist/index.js", + "default": "./dist/index.js" + } + }, + "files": [ + "dist", + "!dist/**/*.test.*", + "!dist/**/*.spec.*" + ], + "svelte": "./dist/index.js", + "types": "./dist/index.d.ts", + "type": "module", + "dependencies": { + "@launchdarkly/svelte-client-sdk": "workspace:^", + "esm-env": "^1.0.0", + "svelte": "^5.4.0" + }, + "devDependencies": { + "@sveltejs/adapter-auto": "^3.0.0", + "@sveltejs/kit": "^2.0.0", + "@sveltejs/package": "^2.0.0", + "@sveltejs/vite-plugin-svelte": "^5.0.1", + "@types/eslint": "8.56.0", + "@typescript-eslint/eslint-plugin": "^6.0.0", + "@typescript-eslint/parser": "^6.0.0", + "eslint": "^8.56.0", + "eslint-config-prettier": "^9.1.0", + "eslint-plugin-svelte": "^2.35.1", + "jsdom": "^24.0.0", + "prettier": "^3.1.1", + "prettier-plugin-svelte": "^3.1.2", + "svelte-check": "^3.6.0", + "tslib": "^2.4.1", + "typescript": "^5.0.0", + "vite": "^6.0.2", + "vitest": "^2.1.8" + } +} diff --git a/packages/sdk/svelte/example/src/app.d.ts b/packages/sdk/svelte/example/src/app.d.ts new file mode 100644 index 0000000000..743f07b2e5 --- /dev/null +++ b/packages/sdk/svelte/example/src/app.d.ts @@ -0,0 +1,13 @@ +// See https://kit.svelte.dev/docs/types#app +// for information about these interfaces +declare global { + namespace App { + // interface Error {} + // interface Locals {} + // interface PageData {} + // interface PageState {} + // interface Platform {} + } +} + +export {}; diff --git a/packages/sdk/svelte/example/src/app.html b/packages/sdk/svelte/example/src/app.html new file mode 100644 index 0000000000..f22aeaad5e --- /dev/null +++ b/packages/sdk/svelte/example/src/app.html @@ -0,0 +1,12 @@ + + + + + + + %sveltekit.head% + + +
%sveltekit.body%
+ + diff --git a/packages/sdk/svelte/example/src/index.test.ts b/packages/sdk/svelte/example/src/index.test.ts new file mode 100644 index 0000000000..e07cbbd725 --- /dev/null +++ b/packages/sdk/svelte/example/src/index.test.ts @@ -0,0 +1,7 @@ +import { describe, it, expect } from 'vitest'; + +describe('sum test', () => { + it('adds 1 + 2 to equal 3', () => { + expect(1 + 2).toBe(3); + }); +}); diff --git a/packages/sdk/svelte/example/src/routes/+layout.svelte b/packages/sdk/svelte/example/src/routes/+layout.svelte new file mode 100644 index 0000000000..a9edddd3aa --- /dev/null +++ b/packages/sdk/svelte/example/src/routes/+layout.svelte @@ -0,0 +1,27 @@ + + + +{#snippet failed(error: unknown, reset: () => void)} +
+

Something failed!

+

There was an error loading the app. Please make sure you have the environment variables properly setup

+ +
+{/snippet} + + + + + +

loading flags...

+
+
diff --git a/packages/sdk/svelte/example/src/routes/+page.svelte b/packages/sdk/svelte/example/src/routes/+page.svelte new file mode 100644 index 0000000000..9595bd334f --- /dev/null +++ b/packages/sdk/svelte/example/src/routes/+page.svelte @@ -0,0 +1,26 @@ + + + + + +
+

this box is lightblue when flag is on ({PUBLIC_LD_FLAG_KEY})

+
+
+

this box is lightyellow when flag is off ({PUBLIC_LD_FLAG_KEY})

+
+
+ + diff --git a/packages/sdk/svelte/example/static/favicon.png b/packages/sdk/svelte/example/static/favicon.png new file mode 100644 index 0000000000..825b9e65af Binary files /dev/null and b/packages/sdk/svelte/example/static/favicon.png differ diff --git a/packages/sdk/svelte/example/svelte.config.js b/packages/sdk/svelte/example/svelte.config.js new file mode 100644 index 0000000000..2b35fe1bef --- /dev/null +++ b/packages/sdk/svelte/example/svelte.config.js @@ -0,0 +1,18 @@ +import adapter from '@sveltejs/adapter-auto'; +import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'; + +/** @type {import('@sveltejs/kit').Config} */ +const config = { + // Consult https://kit.svelte.dev/docs/integrations#preprocessors + // for more information about preprocessors + preprocess: vitePreprocess(), + + kit: { + // adapter-auto only supports some environments, see https://kit.svelte.dev/docs/adapter-auto for a list. + // If your environment is not supported or you settled on a specific environment, switch out the adapter. + // See https://kit.svelte.dev/docs/adapters for more information about adapters. + adapter: adapter() + } +}; + +export default config; diff --git a/packages/sdk/svelte/example/tsconfig.json b/packages/sdk/svelte/example/tsconfig.json new file mode 100644 index 0000000000..6f788f1603 --- /dev/null +++ b/packages/sdk/svelte/example/tsconfig.json @@ -0,0 +1,15 @@ +{ + "extends": "./.svelte-kit/tsconfig.json", + "compilerOptions": { + "allowJs": true, + "checkJs": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "skipLibCheck": true, + "sourceMap": true, + "strict": true, + "module": "NodeNext", + "moduleResolution": "NodeNext" + } +} diff --git a/packages/sdk/svelte/example/vite.config.ts b/packages/sdk/svelte/example/vite.config.ts new file mode 100644 index 0000000000..af28fe93da --- /dev/null +++ b/packages/sdk/svelte/example/vite.config.ts @@ -0,0 +1,11 @@ +import { sveltekit } from '@sveltejs/kit/vite'; +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + plugins: [sveltekit()], + test: { + include: ['src/**/*.{test,spec}.{js,ts,svelte}'], + globals: true, + environment: 'jsdom' + } +}); diff --git a/packages/sdk/svelte/package.json b/packages/sdk/svelte/package.json index f00be2461a..1b4a30af93 100644 --- a/packages/sdk/svelte/package.json +++ b/packages/sdk/svelte/package.json @@ -44,7 +44,6 @@ "test:unit-coverage": "vitest --coverage" }, "peerDependencies": { - "@launchdarkly/js-client-sdk": "workspace:^", "svelte": "^4.0.0" }, "dependencies": { @@ -72,7 +71,6 @@ "eslint-plugin-prettier": "^5.0.0", "eslint-plugin-svelte": "^2.35.1", "jsdom": "^24.0.0", - "launchdarkly-js-test-helpers": "^2.2.0", "prettier": "^3.0.0", "prettier-plugin-svelte": "^3.1.2", "publint": "^0.1.9", diff --git a/packages/sdk/svelte/src/lib/index.ts b/packages/sdk/svelte/src/lib/index.ts index 32c2c870bb..ed62c5043d 100644 --- a/packages/sdk/svelte/src/lib/index.ts +++ b/packages/sdk/svelte/src/lib/index.ts @@ -1,5 +1,5 @@ // Reexport your entry components here -export * as LDClient from './client/SvelteLDClient.js'; +export { LD } from './client/SvelteLDClient.js'; // Export Components export { default as LDProvider } from './provider/LDProvider.svelte';