@uniformdev/uniform-nuxt 16.0.1-nuxt.158 → 16.2.0

package/README.md

@@ -1,9 +1,96 @@
-# Uniform Nuxt Module
+# Uniform Nuxt module
 
-Documentation will be added very soon!
+## Getting started
+
+Install the peer dependencies of the module (if you haven't already):
+```
+npm i @uniformdev/canvas @uniformdev/canvas-vue @uniformdev/context @uniformdev/context-vue
+```
+Install the module
+```
+npm i @uniformdev/uniform-nuxt
+```
+
+Add the module to you Nuxt config:
+
+```ts
+import { defineNuxtConfig } from 'nuxt';
+
+export default defineNuxtConfig({
+  transpile: ['@uniformdev/canvas-vue', '@uniformdev/context-vue'],
+  modules: [
+    [
+      '@uniformdev/uniform-nuxt',
+      {
+        projectId: process.env.UNIFORM_PROJECT_ID,
+        readOnlyApiKey: process.env.UNIFORM_API_KEY,
+      },
+    ],
+  ],
+});
+```
+
+## Features
+
+- Auto-registers the needed Uniform components.
+- Creates a Canvas client automatically.
+- Creates a Uniform Context instance and provides it through the whole app, without the need of a wrapping component.
+- Provides a handy `$useComposition` composable, build on top of Nuxt's [useAsyncData](https://v3.nuxtjs.org/api/composables/use-async-data).
+- Handle Live Preview.
+- Watches query string change, which Nuxt doesn't do by default.
+
+## API reference
+
+### Options
+These are the option you pass to the module in `nuxt.config.ts`.
+
+| Option | Type | Description |
+|---|---|---|
+| `projectId`* |  string | The ID of the Uniform project you want to use in your app. |
+| `readOnlyApiKey`* |  string | An API key that has read permissions to your Uniform project. ⚠️ Make sure the API key has only read access, because it's used in Nuxt's public runtime config |
+| `manifest` |  ManifestV2 | The Uniform Context manifest. This one is usually fetched right before the app is started using Uniform's CLI. Uniform Context won't be enabled if a manifest is missing. |
+| `outputType` | 'standard' \| 'edge' | Set it to 'edge' when building the app for the edge using [NESI technology](https://docs.uniform.app/context/reference/netlify). Defaults to 'standard' |
+| `apiHost` | string | The host to be used when calling the API. Defaults to 'https://uniform.app' |
+\* Required
+
+### Injected in the Nuxt instance
+These are the properties that the module injects in the Nuxt app instance, so you can use them anywhere in your app.
+
+| Property | Type | Description |
+|---|---|---|
+| `$useComposition` |  function | A compasable that you can use to fetch a Canvas composition. It's preview-aware, it will automatically fetch the draft composition if the app is in preview mode, otherwise it will return the published one. It uses Suspense under the hood, so you can have access to the error and pending states of the request |
+| `$useUniformContext` |  function | A compasable that returns the current Uniform Context instance which allows you interact with the context such updating the scores and so on. It also returns other provided properties such as `outputType` |
+| `$preview` |  object \| undefined | This object is only defined in preview mode, so you can use it to adjust your app if it's in preview mode. It contains the slug of the current composition. |
+| `$uniformCanvasClient` |  CanvasClient | Returns the Canvas client which you can use to fetch or update compositions. For composition fetching, it's recommended to use `$useComposition` instead. |
+| `uniformCanvasClient` |  CanvasClient | Returns the Canvas client which you can use to fetch or update compositions. For composition fetching, it's recommended to use `$useComposition` instead. |
+
+### Components
+These are the components that the module auto registers for you, so you can use them without import.
+
+#### <Composition />
+This component wraps the whole composition, it 
+
+| Prop | Type | Description |
+|---|---|---|
+| `data`* |  string | The data of the composition to be rendered, this is usually the `composition` object that you get from `$useComposition` |
+| `resolveRenderer` |  function | This function is responsible of mapping Canvas components to Vue components. It takes a ComponentInstance object and should return a Vue component (usually based on the component `type`). If no resolver is provided, it will try to resolve the componnet in on the global context of the app, so if you have globally defined components, it will try to map them based on the `name` of the Vue component and the `type` of Canvas component|
+
+* Required
+
+#### <SlotContent />
+This component is used to render the slots of a composition, and it can be only used inside a `<Composition />`.
+You can nest `<SlotContent />` inside each other if you have nested slots.
+
+| Prop | Type | Description |
+|---|---|---|
+| `name` |  string | The name of the Canvas slot to render. If no name is provided, all the slots will be rendered. This is not recommended as the order is not guaranteed |
+
+## Example
+
+Here are some example where the module is used:
+- https://github.com/uniformdev/uniformconf-nuxt
+- https://github.com/uniformdev/nuxt-canvas-nuxt
 
-In the meantime, here is a working example on how to use the module:
-https://github.com/uniformdev/uniformconf-nuxt/blob/main/nuxt.config.ts
 
 
 -----

package/dist/module.json

@@ -1,5 +1,5 @@
 {
   "name": "nuxt-uniform",
   "configKey": "uniform",
-  "version": "16.0.1-nuxt.158+fac0325ba"
+  "version": "16.2.0"
 }

package/dist/runtime/plugin.mjs

@@ -8,7 +8,7 @@ import {
   useState,
   useCookie
 } from "#app";
-import { watch } from "vue-demi";
+import { watch, toRaw } from "vue-demi";
 import {
   CanvasClient,
   CANVAS_DRAFT_STATE,
@@ -17,6 +17,7 @@ import {
 import {
   Context,
   CookieTransitionDataStore,
+  enableContextDevTools,
   UNIFORM_DEFAULT_COOKIE_NAME
 } from "@uniformdev/context";
 import { Composition, SlotContent, useCompositionEventEffect } from "@uniformdev/canvas-vue";
@@ -52,12 +53,14 @@ function setupContext(nuxtApp) {
   let uniformContext;
   if (options.manifest) {
     console.log("uniform-nuxt: \u{1F4DC} found a manifest, will initialize Context");
+    const manifestAsSimpleObject = toRaw(options.manifest);
     uniformContext = new Context({
       defaultConsent: true,
-      manifest: options.manifest,
+      manifest: manifestAsSimpleObject,
       transitionStore: new CookieTransitionDataStore({
         serverCookieValue: uniformCookie
-      })
+      }),
+      plugins: [enableContextDevTools()]
     });
   }
   provideUniformContext({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/uniform-nuxt",
-  "version": "16.0.1-nuxt.158+fac0325ba",
+  "version": "16.2.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -30,16 +30,15 @@
   "devDependencies": {
     "@nuxt/module-builder": "0.1.7",
     "@nuxtjs/eslint-config-typescript": "10.0.0",
-    "@uniformdev/canvas": "^16.0.1-nuxt.158+fac0325ba",
-    "@uniformdev/canvas-vue": "^16.0.1-nuxt.158+fac0325ba",
-    "@uniformdev/context": "^16.0.1-nuxt.158+fac0325ba",
-    "@uniformdev/context-vue": "^16.0.1-nuxt.158+fac0325ba",
+    "@uniformdev/canvas": "^16.2.0",
+    "@uniformdev/canvas-vue": "^16.2.0",
+    "@uniformdev/context": "^16.2.0",
+    "@uniformdev/context-vue": "^16.2.0",
     "esbuild": "0.13.15",
     "eslint": "latest",
     "nuxt": "^3.0.0-rc.4"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "gitHead": "fac0325bab53217a4c5a3c63d549812678f484f3"
+  }
 }