feat(vue): add @tryabby/vue integration

.changeset/vue-integration.md

@@ -0,0 +1,7 @@
+---
+"@tryabby/vue": minor
+---
+
+Add the `@tryabby/vue` integration with `useAbby`, `useFeatureFlag` and
+`useRemoteConfig` composables, an `AbbyProvider` component and an installable
+Vue plugin.

apps/docs/pages/integrations/_meta.json

@@ -3,6 +3,7 @@
   "react": "React",
   "remix": "Remix",
   "svelte": "Svelte",
+  "vue": "Vue",
   "angular": "Angular",
   "node": "Node",
   "express": "Express",

apps/docs/pages/integrations/vue.mdx

@@ -0,0 +1,187 @@
+import { Tab, Tabs, Callout } from "nextra-theme-docs";
+
+# Vue
+
+Our Vue integration works with Vue 3 (SPAs as well as server side rendered apps)
+and with Nuxt.
+
+## Installation
+
+To get started make sure to install the package using your favorite package manager.
+
+<Tabs items={["npm", "yarn", "pnpm"]}>
+  <Tab>
+    ```bash
+    npm i @tryabby/vue
+    ```
+    </Tab>
+
+  <Tab>
+    ```bash
+    yarn add @tryabby/vue
+    ```
+</Tab>
+  <Tab>
+    ```bash
+    pnpm i @tryabby/vue
+    ```
+    </Tab>
+</Tabs>
+
+## Usage
+
+### Create your config
+
+To use Abby you need to create your config first. You can do this by creating a
+file called `abby.config.ts` in your `root` folder. This file will be used to
+configure your project.
+
+```ts
+// abby.config.ts
+import { defineConfig } from "@tryabby/vue";
+
+export default defineConfig({
+  projectId: "<YOUR_PROJECT_ID>",
+  currentEnvironment: import.meta.env.MODE,
+  environments: ["production", "development"],
+  tests: {
+    test: { variants: ["A", "B"] },
+    footer: { variants: ["dark", "orange", "green"] },
+    // ... your tests
+  },
+  flags: ["darkMode", "newFeature"],
+  remoteConfig: {
+    customButtonText: "String",
+  },
+});
+```
+
+### Create your instance
+
+To use Abby in your code you will need to create your typed composables first.
+You can do this by using the `createAbby` function. Please copy the id of your
+project from the dashboard to get started.
+
+```ts
+import { createAbby } from "@tryabby/vue";
+import abbyConfig from "../abby.config";
+
+const { AbbyProvider, useAbby } = createAbby(abbyConfig);
+```
+
+<Callout type="info">
+  Call `createAbby` once in its own module and import the returned composables
+  where you need them - that keeps the types of your tests, flags and remote
+  config available across your whole app.
+</Callout>
+
+### Wrap your Application
+
+Wrap your application in the `AbbyProvider`. The provider loads your project
+data and provides it to all components below it.
+
+```html
+<script setup lang="ts">
+  import { AbbyProvider } from "./abby";
+</script>
+
+<template>
+  <AbbyProvider>
+    <RouterView />
+  </AbbyProvider>
+</template>
+```
+
+If you prefer to use a plugin you can also install Abby on your app instance.
+The composables need to be created outside of your components for this.
+
+```ts
+// main.ts
+import { createApp } from "vue";
+import { AbbyPlugin } from "./abby";
+import App from "./App.vue";
+
+createApp(App).use(AbbyPlugin).mount("#app");
+```
+
+### Use the composables
+
+The composables can be used inside the `setup` function of your components. They
+all return `ComputedRef`s, so they stay in sync when new project data arrives.
+
+#### useAbby
+
+`useAbby` takes the name of your test and returns the currently selected variant
+as well as the `onAct` function, which you can call to track a conversion.
+
+```html
+<script setup lang="ts">
+  import { useAbby } from "./abby";
+
+  const { variant, onAct } = useAbby("test");
+</script>
+
+<template>
+  <div>
+    <p v-if="variant === 'A'">Variant A</p>
+    <p v-else>Variant B</p>
+
+    <button type="button" @click="onAct">Buy now</button>
+  </div>
+</template>
+```
+
+#### useFeatureFlag
+
+`useFeatureFlag` takes the name of your feature flag and returns its value.
+
+```html
+<script setup lang="ts">
+  import { useFeatureFlag } from "./abby";
+
+  const darkModeEnabled = useFeatureFlag("darkMode");
+</script>
+
+<template>
+  <div :class="{ dark: darkModeEnabled }">Hello World</div>
+</template>
+```
+
+#### useRemoteConfig
+
+`useRemoteConfig` takes the name of your remote config and returns its value.
+
+```html
+<script setup lang="ts">
+  import { useRemoteConfig } from "./abby";
+
+  const buttonText = useRemoteConfig("customButtonText");
+</script>
+
+<template>
+  <button type="button">{{ buttonText }}</button>
+</template>
+```
+
+### Nuxt
+
+For Nuxt you can put your `createAbby` instance into a plugin and pass the
+project data which is fetched during server side rendering as `initialData`.
+This way the first render already contains your variants and flags.
+
+```ts
+// plugins/abby.ts
+import { createAbby } from "./abby";
+
+const { AbbyPlugin } = createAbby(abbyConfig);
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.use(AbbyPlugin);
+});
+```
+
+<Callout type="info">
+  `AbbyProvider` accepts an `initialData` prop (an `AbbyDataResponse` from
+  `@tryabby/core`). If you pass it, the provider will not fetch your project data
+  on the client, which avoids a hydration mismatch.
+</Callout>

apps/docs/pages/reference/_meta.json

@@ -3,6 +3,7 @@
   "react": "React",
   "remix": "Remix",
   "svelte": "Svelte",
+  "vue": "Vue",
   "angular": "Angular",
   "http": "HTTP API",
   "cli": "CLI",

apps/docs/pages/reference/vue.mdx

@@ -0,0 +1,89 @@
+# API Reference (Vue)
+
+## createAbby
+
+### Parameters
+
+The `createAbby` function takes an object as a parameter. The object can contain the following properties:
+
+| Name               | Type     | Required | Description                                                                                                                                       |
+| ------------------ | -------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| projectId          | `string` |    YES   | The ID of your project in Abby                                                                                                                    |
+| apiUrl             | `string` |          | The URL of the Abby API. Defaults to the hosted version                                                                                            |
+| currentEnvironment | `string` |    YES   | The current environment of your application                                                                                                        |
+| tests              | `object` |          | An object containing your defined A/B Tests                                                                                                       |
+| flags              | `array`  |          | An array containing your defined Feature Flags                                                                                                    |
+| remoteConfig       | `object` |          | An object containing the name of your remote config and their type                                                                                |
+| settings           | `object` |          | An object with additional settings for Abby                                                                                                        |
+| user               | `object` |          | Optional configuration for user properties that can be used for targeting feature flags. This enables conditional rules based on user attributes. |
+
+### Return value
+
+| Name                       | Type                                                | Description                                                                             |
+| -------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `AbbyProvider`             | `Component`                                         | Loads the project data and provides it to all child components                            |
+| `AbbyPlugin`               | `Plugin`                                            | Vue plugin, install it with `app.use(AbbyPlugin, initialData?)`                           |
+| `useAbby`                  | `(name, lookupObject?) => { variant, onAct }`        | Returns the current variant of a test and a function to track an act                       |
+| `useFeatureFlag`           | `(name) => ComputedRef<boolean>`                     | Returns the value of a feature flag                                                       |
+| `useFeatureFlags`          | `() => ComputedRef<Array<{ name, value }>>`          | Returns all feature flags with their current value                                        |
+| `useRemoteConfig`          | `(name) => ComputedRef<value>`                       | Returns the value of a remote config                                                      |
+| `useRemoteConfigVariables` | `() => ComputedRef<Array<{ name, value }>>`          | Returns all remote config variables with their current value                               |
+| `getFeatureFlagValue`      | `(name) => boolean`                                  | Non reactive helper to read a feature flag                                                |
+| `getRemoteConfig`          | `(name) => value`                                    | Non reactive helper to read a remote config                                               |
+| `getABTestValue`           | `(name, lookupObject?) => value`                     | Non reactive helper to read the variant of a test                                         |
+| `getVariants`              | `(name) => string[]`                                 | Returns all variants of a test                                                            |
+| `getABResetFunction`       | `() => void`                                          | Returns a function which resets the persisted variant of a test                           |
+| `updateUserProperties`     | `(userProperties) => void`                           | Updates the user properties which are sent to Abby                                        |
+| `__abby__`                 | `Abby`                                               | The underlying `Abby` instance of `@tryabby/core`                                          |
+
+## AbbyProvider
+
+### Props
+
+| Name          | Type               | Required | Description                                                                                                |
+| ------------- | ------------------ | :------: | ---------------------------------------------------------------------------------------------------------- |
+| `initialData` | `AbbyDataResponse` |          | Project data which is used instead of fetching it from the Abby API (for example during server rendering)   |
+
+## useAbby
+
+### Parameters
+
+| Name           | Type     | Required | Description                                                                            |
+| -------------- | -------- | :------: | -------------------------------------------------------------------------------------- |
+| `name`         | `string` |    YES   | The name of your A/B test                                                               |
+| `lookupObject` | `object` |          | A map from variant to the value you want to get back from `variant`, e.g. a component    |
+
+### Return value
+
+| Name      | Type                                  | Description                                                |
+| --------- | ------------------------------------- | ---------------------------------------------------------- |
+| `variant` | `ComputedRef<Variant \| LookupValue>` | The currently selected variant (or its mapped value)        |
+| `onAct`   | `() => void`                          | Call this function to track an act for the current variant   |
+
+## useFeatureFlag
+
+### Parameters
+
+| Name   | Type     | Required | Description                     |
+| ------ | -------- | :------: | ------------------------------- |
+| `name` | `string` |    YES   | The name of your feature flag   |
+
+### Return value
+
+| Name    | Type                    | Description                   |
+| ------- | ----------------------- | ----------------------------- |
+| `value` | `ComputedRef<boolean>`  | The value of the feature flag  |
+
+## useRemoteConfig
+
+### Parameters
+
+| Name   | Type     | Required | Description                    |
+| ------ | -------- | :------: | ------------------------------ |
+| `name` | `string` |    YES   | The name of your remote config  |
+
+### Return value
+
+| Name    | Type                        | Description                     |
+| ------- | --------------------------- | ------------------------------- |
+| `value` | `ComputedRef<ConfigValue>`  | The value of the remote config  |

packages/vue/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+coverage