@okendo/shopify-hydrogen 0.0.3 → 0.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +410 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,7 +7,404 @@ Currently we support server side components for 2 widgets:
|
|
|
7
7
|
1. Reviews List
|
|
8
8
|
2. Star Ratings
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
<br/>
|
|
11
|
+
|
|
12
|
+
# Table of contents
|
|
13
|
+
|
|
14
|
+
1. [What is Okendo Shopify Hydrogen](#introduction)
|
|
15
|
+
2. [Guided Installation](#installation)
|
|
16
|
+
1. [Configure Hydrogen App](#1-configure-hydrogen-app-config)
|
|
17
|
+
2. [Expose Shopify Metafields](#2-expose-shopify-metafields)
|
|
18
|
+
3. [How to Use Okendo Hydrogen Components In Your Hydrogen Apps](#3-how-to-use-okendo-hydrogen-components-in-your-hydrogen-app)
|
|
19
|
+
4. [Component Props](#component-props)
|
|
20
|
+
5. [NPM Component Terminology/Defintions](#npm-component-definitions)
|
|
21
|
+
6. [View Our Okendo Sample Hydrogen App](#view-our-okendo-sample-hydrogen-app)
|
|
22
|
+
|
|
23
|
+
<br/><br/>
|
|
24
|
+
|
|
25
|
+
# What is Okendo Shopify Hydrogen? <a id="introduction" name="introduction"></a>
|
|
26
|
+
|
|
27
|
+
Okendo Shopify Hydrogen is a React component library to be used in Shopify Hydrogen apps. This utilises [Shopify’s Hydrogen framework](https://shopify.dev/custom-storefronts/hydrogen/framework) which is used to create custom storefronts using both server-side rendered and client-side rendered React components.
|
|
28
|
+
|
|
29
|
+
The purpose of this library is for a Hydrogen-based React Shopify storefront to import this library so that the Okendo Reviews List and Okendo Star Ratings components can be rendered within their React application, providing [Okendo’s reviews display functionality](https://www.okendo.io/blog/widget-plus/).
|
|
30
|
+
|
|
31
|
+
<br/>
|
|
32
|
+
|
|
33
|
+
# Guided Installation <a id="installation" name="installation"></a>
|
|
34
|
+
|
|
35
|
+
The purpose of this documentation is to guide you on the following:
|
|
36
|
+
|
|
37
|
+
- How to configure your Shopify store ready for Okendo Shopify Hydrogen.
|
|
38
|
+
- How to install and configure Okendo Shopify Hydrogen components in your Shopify Hydrogen app.
|
|
39
|
+
|
|
40
|
+
<br/>
|
|
41
|
+
|
|
42
|
+
## Requirements
|
|
43
|
+
|
|
44
|
+
- You have an existing Shopify store.
|
|
45
|
+
- You have an existing Hydrogen app. ([Learn how to create a Hydrogen app](https://shopify.dev/custom-storefronts/hydrogen/getting-started/create))
|
|
46
|
+
- You have a current Okendo Reviews subscription and have the **Okendo: Product Reviews & UCG** app installed and configured.
|
|
47
|
+
- You have an existing Shopify custom app with Storefront access token. ([Learn how to configure Shopify Storefront](https://www.notion.so/Configure-Shopify-Storefront-9e78e31bb4d94546aa1d037367c6a0b8))
|
|
48
|
+
|
|
49
|
+
<br/>
|
|
50
|
+
|
|
51
|
+
## 1. Configure Hydrogen app config <a id="1-configure-hydrogen-app-config" name="1-configure-hydrogen-app-config"></a>
|
|
52
|
+
|
|
53
|
+
1. Open **hydrogen.config.js** in your project.
|
|
54
|
+
2. Make the following changes and save the file:
|
|
55
|
+
- Update `storeDomain` to specify your store's domain name.
|
|
56
|
+
- Update `storefrontToken` to specify your Storefront API access token.
|
|
57
|
+
|
|
58
|
+
<br/>
|
|
59
|
+
|
|
60
|
+
## 2. Expose Shopify Metafields <a id="2-expose-shopify-metafields" name="2-expose-shopify-metafields"></a>
|
|
61
|
+
|
|
62
|
+
Okendo Reviews utilise Product and Shop specific [metafields](https://shopify.dev/api/examples/metafields) in order to function and provide a seamless user experience. You will need to expose these metafields so that they can be retrieved by your Hydrogen app.
|
|
63
|
+
|
|
64
|
+
At this point in time, unfortunately Shopify does not have a way of exposing Shop Metafields through their admin UI.
|
|
65
|
+
|
|
66
|
+
The preferred method to expose Metafields is to [contact Okendo Support](mailto:support@okendo.io).
|
|
67
|
+
|
|
68
|
+
<br/>
|
|
69
|
+
|
|
70
|
+
### For Technical/Advanced Users
|
|
71
|
+
|
|
72
|
+
<details>
|
|
73
|
+
<summary>Learn How to Expose Metafields Via The Storefront API</summary>
|
|
74
|
+
|
|
75
|
+
# Exposing Metafields via GraphQL
|
|
76
|
+
|
|
77
|
+
## Using Curl
|
|
78
|
+
|
|
79
|
+
You can also expose the required Okendo Shopify Metafields by using GraphQL with curl.
|
|
80
|
+
|
|
81
|
+
1. Open a new terminal or PowerShell window.
|
|
82
|
+
2. Run the following command to expose the `WidgetPreRenderStyleTag` Shop Metafield.
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
curl -X POST \
|
|
86
|
+
https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
|
|
87
|
+
-H 'Content-Type: application/graphql' \
|
|
88
|
+
-H 'X-Shopify-Access-Token: {access_token}' \
|
|
89
|
+
-d '
|
|
90
|
+
mutation {
|
|
91
|
+
metafieldStorefrontVisibilityCreate(
|
|
92
|
+
input: {
|
|
93
|
+
namespace: "okendo"
|
|
94
|
+
key: "WidgetPreRenderStyleTags"
|
|
95
|
+
ownerType: SHOP
|
|
96
|
+
}
|
|
97
|
+
) {
|
|
98
|
+
metafieldStorefrontVisibility {
|
|
99
|
+
id
|
|
100
|
+
}
|
|
101
|
+
userErrors {
|
|
102
|
+
field
|
|
103
|
+
message
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
'
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
3. Run the following command to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
curl -X POST \
|
|
114
|
+
https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
|
|
115
|
+
-H 'Content-Type: application/graphql' \
|
|
116
|
+
-H 'X-Shopify-Access-Token: {access_token}' \
|
|
117
|
+
-d '
|
|
118
|
+
mutation {
|
|
119
|
+
metafieldStorefrontVisibilityCreate(
|
|
120
|
+
input: {
|
|
121
|
+
namespace: "okendo"
|
|
122
|
+
key: "WidgetPreRenderBodyStyleTags"
|
|
123
|
+
ownerType: SHOP
|
|
124
|
+
}
|
|
125
|
+
) {
|
|
126
|
+
metafieldStorefrontVisibility {
|
|
127
|
+
id
|
|
128
|
+
}
|
|
129
|
+
userErrors {
|
|
130
|
+
field
|
|
131
|
+
message
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
'
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
4. Run the following command to expose the `ReviewsWidgetSnippet` Product Metafield.
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
curl -X POST \
|
|
142
|
+
https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
|
|
143
|
+
-H 'Content-Type: application/graphql' \
|
|
144
|
+
-H 'X-Shopify-Access-Token: {access_token}' \
|
|
145
|
+
-d '
|
|
146
|
+
mutation {
|
|
147
|
+
metafieldStorefrontVisibilityCreate(
|
|
148
|
+
input: {
|
|
149
|
+
namespace: "okendo"
|
|
150
|
+
key: "ReviewsWidgetSnippet"
|
|
151
|
+
ownerType: PRODUCT
|
|
152
|
+
}
|
|
153
|
+
) {
|
|
154
|
+
metafieldStorefrontVisibility {
|
|
155
|
+
id
|
|
156
|
+
}
|
|
157
|
+
userErrors {
|
|
158
|
+
field
|
|
159
|
+
message
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
'
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
5. Run the following command to expose the `StarRatingSnippet` the Product Metafield.
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
curl -X POST \
|
|
170
|
+
https://{shop}.myshopify.com/admin/api/2022-04/graphql.json \
|
|
171
|
+
-H 'Content-Type: application/graphql' \
|
|
172
|
+
-H 'X-Shopify-Access-Token: {access_token}' \
|
|
173
|
+
-d '
|
|
174
|
+
mutation {
|
|
175
|
+
metafieldStorefrontVisibilityCreate(
|
|
176
|
+
input: {
|
|
177
|
+
namespace: "okendo"
|
|
178
|
+
key: "StarRatingSnippet"
|
|
179
|
+
ownerType: PRODUCT
|
|
180
|
+
}
|
|
181
|
+
) {
|
|
182
|
+
metafieldStorefrontVisibility {
|
|
183
|
+
id
|
|
184
|
+
}
|
|
185
|
+
userErrors {
|
|
186
|
+
field
|
|
187
|
+
message
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
'
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Using GraphQL IDE
|
|
195
|
+
|
|
196
|
+
1. Open your GraphQL IDE (such as Postman) and make a `POST` request with the following details:
|
|
197
|
+
|
|
198
|
+
- **URL:** https://{shop}.myshopify.com/admin/api/2022-04/graphql.json
|
|
199
|
+
- **Headers:** - X-Shopify-Access-Token: {access_token} - Content-Type: application/json 2. Execute the following request to expose the `WidgetPreRenderStyleTag` Shop Metafield.
|
|
200
|
+
|
|
201
|
+
```graphql
|
|
202
|
+
mutation {
|
|
203
|
+
metafieldStorefrontVisibilityCreate(
|
|
204
|
+
input: {
|
|
205
|
+
namespace: "okendo"
|
|
206
|
+
key: "WidgetPreRenderStyleTags"
|
|
207
|
+
ownerType: SHOP
|
|
208
|
+
}
|
|
209
|
+
) {
|
|
210
|
+
metafieldStorefrontVisibility {
|
|
211
|
+
id
|
|
212
|
+
}
|
|
213
|
+
userErrors {
|
|
214
|
+
field
|
|
215
|
+
message
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
3. Execute the following request to expose the `WidgetPreRenderBodyStyleTags` Shop Metafield.
|
|
222
|
+
|
|
223
|
+
```graphql
|
|
224
|
+
mutation {
|
|
225
|
+
metafieldStorefrontVisibilityCreate(
|
|
226
|
+
input: {
|
|
227
|
+
namespace: "okendo"
|
|
228
|
+
key: "WidgetPreRenderBodyStyleTags"
|
|
229
|
+
ownerType: SHOP
|
|
230
|
+
}
|
|
231
|
+
) {
|
|
232
|
+
metafieldStorefrontVisibility {
|
|
233
|
+
id
|
|
234
|
+
}
|
|
235
|
+
userErrors {
|
|
236
|
+
field
|
|
237
|
+
message
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
4. Execute the following request to expose the `ReviewsWidgetSnippet` Product Metafield.
|
|
244
|
+
|
|
245
|
+
```graphql
|
|
246
|
+
mutation {
|
|
247
|
+
metafieldStorefrontVisibilityCreate(
|
|
248
|
+
input: {
|
|
249
|
+
namespace: "okendo"
|
|
250
|
+
key: "ReviewsWidgetSnippet"
|
|
251
|
+
ownerType: PRODUCT
|
|
252
|
+
}
|
|
253
|
+
) {
|
|
254
|
+
metafieldStorefrontVisibility {
|
|
255
|
+
id
|
|
256
|
+
}
|
|
257
|
+
userErrors {
|
|
258
|
+
field
|
|
259
|
+
message
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
5. Execute the following request to expose the `StarRatingSnippet` the Product Metafield.
|
|
266
|
+
|
|
267
|
+
```graphql
|
|
268
|
+
mutation {
|
|
269
|
+
metafieldStorefrontVisibilityCreate(
|
|
270
|
+
input: {
|
|
271
|
+
namespace: "okendo"
|
|
272
|
+
key: "StarRatingSnippet"
|
|
273
|
+
ownerType: PRODUCT
|
|
274
|
+
}
|
|
275
|
+
) {
|
|
276
|
+
metafieldStorefrontVisibility {
|
|
277
|
+
id
|
|
278
|
+
}
|
|
279
|
+
userErrors {
|
|
280
|
+
field
|
|
281
|
+
message
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**References**
|
|
288
|
+
|
|
289
|
+
[https://shopify.dev/api/examples/metafields#step-1-expose-metafields](https://shopify.dev/api/examples/metafields#step-1-expose-metafields)
|
|
290
|
+
[https://shopify.dev/api/admin-graphql/2022-04/mutations/metafieldstorefrontvisibilitycreate](https://shopify.dev/api/admin-graphql/2022-04/mutations/metafieldstorefrontvisibilitycreate)
|
|
291
|
+
</details>
|
|
292
|
+
|
|
293
|
+
<br/><br/>
|
|
294
|
+
|
|
295
|
+
## 3. How to Use Okendo Hydrogen Components In Your Hydrogen App <a id="3-how-to-use-okendo-hydrogen-components-in-your-hydrogen-app" name="3-how-to-use-okendo-hydrogen-components-in-your-hydrogen-app"></a>
|
|
296
|
+
|
|
297
|
+
### Installation
|
|
298
|
+
|
|
299
|
+
1. In your Hydrogen app directory, run `npm install @okendo/shopify-hydrogen` inside a terminal or PowerShell window.
|
|
300
|
+
2. Open **vite.config.js** and add `import okendo from '@okendo/shopify-hydrogen/plugin` to the list of imports.
|
|
301
|
+
3. Add `okendo()` to the list of `plugins`.
|
|
302
|
+
|
|
303
|
+
```tsx
|
|
304
|
+
/* **vite.config.js */**
|
|
305
|
+
import {defineConfig} from 'vite';
|
|
306
|
+
import hydrogen from '@shopify/hydrogen/plugin';
|
|
307
|
+
import okendo from '@okendo/shopify-hydrogen/plugin';
|
|
308
|
+
|
|
309
|
+
// https://vitejs.dev/config/
|
|
310
|
+
export default defineConfig({
|
|
311
|
+
plugins: [hydrogen(), okendo()],
|
|
312
|
+
optimizeDeps: {include: ['@headlessui/react']},
|
|
313
|
+
test: {
|
|
314
|
+
globals: true,
|
|
315
|
+
testTimeout: 10000,
|
|
316
|
+
hookTimeout: 10000,
|
|
317
|
+
},
|
|
318
|
+
});
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
4. Open **App.server.jsx** and import `OkendoProvider`.
|
|
322
|
+
5. Include the `OkendoProvider` as shown below.
|
|
323
|
+
|
|
324
|
+
```tsx
|
|
325
|
+
/* **App.server.jsx */**
|
|
326
|
+
import { OkendoProvider } from '@okendo/shopify-hydrogen';
|
|
327
|
+
|
|
328
|
+
function App() {
|
|
329
|
+
return (
|
|
330
|
+
<Suspense fallback={<LoadingFallback />}>
|
|
331
|
+
<ShopifyProvider>
|
|
332
|
+
<!-- *** Include OkendoProvider HERE *** -->
|
|
333
|
+
<OkendoProvider subscriberId={okendo_subscriber_id} />
|
|
334
|
+
<ServerCartProvider>
|
|
335
|
+
<DefaultSeo />
|
|
336
|
+
<Router>
|
|
337
|
+
<FileRoutes />
|
|
338
|
+
<Route path="*" page={<NotFound />} />
|
|
339
|
+
</Router>
|
|
340
|
+
</ServerCartProvider>
|
|
341
|
+
<PerformanceMetrics />
|
|
342
|
+
{import.meta.env.DEV && <PerformanceMetricsDebug />}
|
|
343
|
+
</ShopifyProvider>
|
|
344
|
+
</Suspense>
|
|
345
|
+
);
|
|
346
|
+
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
### **Widget Usage**
|
|
350
|
+
|
|
351
|
+
- Import `OkendoReviewsWidget` and `OkendoStarRating` and use as JSX components. Pass in the Shopify product ID as a prop.
|
|
352
|
+
- The `productId` prop is optional for the `OkendoReviewsWidget`. Not providing will mean that the widget will display reviews for all products, which is ideal for homepages or collection pages.
|
|
353
|
+
|
|
354
|
+
```tsx
|
|
355
|
+
import {
|
|
356
|
+
OkendoReviewsWidget,
|
|
357
|
+
OkendoStarRating,
|
|
358
|
+
} from "@okendo/shopify-hydrogen";
|
|
359
|
+
|
|
360
|
+
const okendoReviewsWidget = <OkendoReviewsWidget productId={product.id} />;
|
|
361
|
+
const okendoStarRating = <OkendoStarRating productId={product.id} />;
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
> ℹ️ If you are wanting to use Okendo server components within React client components, you must pass the component in as a prop to the client component passed down from another server component. Otherwise, you can use the component directly in a server component. [Learn more here](https://shopify.dev/api/hydrogen/components#customizing-hydrogen-components).
|
|
365
|
+
|
|
366
|
+
<br/>
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## Component Props <a id="component-props" name="component-props"></a>
|
|
371
|
+
|
|
372
|
+
<br/>
|
|
373
|
+
|
|
374
|
+
### OkendoProviderProps
|
|
375
|
+
|
|
376
|
+
| Name | Type | Description | Optional |
|
|
377
|
+
| ------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
378
|
+
| subscriberId | string | The Okendo subscriber ID. | no |
|
|
379
|
+
| apiDomain | string | To override the default Okendo API Domain. (Default: api.okendo.io/v1) | yes |
|
|
380
|
+
| cdnDomain | string | To override the default Okendo CDN domain. (Default: d3hw6dc1ow8pp2.cloudfront.net) | yes |
|
|
381
|
+
| productUrlFormatOverride | (product: Pick<ReviewWithProductPublic, 'productHandle' \| 'productId' \| 'variantId'>) => string; | By default, we use Hydrogen’s default product routing. **Advanced Usage Only:** Function hook which allows the custom configuration of the Shopify product URLs from the Okendo Reviews Widget. | yes |
|
|
382
|
+
|
|
383
|
+
<br/><br/>
|
|
384
|
+
|
|
385
|
+
### OkendoReviewsWidgetProps
|
|
386
|
+
|
|
387
|
+
| Name | Type | Description | Optional |
|
|
388
|
+
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
389
|
+
| productId | string | The Shopify Product ID. If provided, the Reviews Widget will be configured to display reviews specific to that product. Otherwise, the Reviews Widget will display reviews for all products. | yes |
|
|
390
|
+
|
|
391
|
+
<br/>
|
|
392
|
+
|
|
393
|
+
### OkendoStarRatingProps
|
|
394
|
+
|
|
395
|
+
| Name | Type | Description | Optional |
|
|
396
|
+
| --------- | ------ | ----------------------- | -------- |
|
|
397
|
+
| productId | string | The Shopify Product ID. | no |
|
|
398
|
+
|
|
399
|
+
<br/>
|
|
400
|
+
|
|
401
|
+
---
|
|
402
|
+
|
|
403
|
+
<br/>
|
|
404
|
+
|
|
405
|
+
<a name="npmdefinitions"></a>
|
|
406
|
+
|
|
407
|
+
## NPM Component Definitions <a id="npm-component-definitions" name="npm-component-definitions"></a>
|
|
11
408
|
|
|
12
409
|
### OkendoProvider.server
|
|
13
410
|
|
|
@@ -25,21 +422,24 @@ The final server side render/output includes:
|
|
|
25
422
|
- Okendo Initialisation Script: This is used to render the widgets on the page.
|
|
26
423
|
- Any custom CSS specified in the Okendo Admin.
|
|
27
424
|
|
|
425
|
+
<br/>
|
|
426
|
+
|
|
28
427
|
### OkendoStarRating.server
|
|
29
428
|
|
|
30
|
-
This is the server-side rendered Star Rating widget
|
|
429
|
+
This is the server-side rendered Star Rating widget - It then invokes the client side `OkendoWidget.client.tsx` component to perform client side hydration.
|
|
430
|
+
|
|
431
|
+
<br/>
|
|
31
432
|
|
|
32
433
|
### OkendoReviewsWidget.server
|
|
33
434
|
|
|
34
|
-
This is the server-side rendered Reviews List widget
|
|
435
|
+
This is the server-side rendered Reviews List widget - It then invokes the client side `OkendoWidget.client.tsx` component to perform client side hydration.
|
|
436
|
+
|
|
437
|
+
---
|
|
35
438
|
|
|
36
|
-
|
|
439
|
+
<br/>
|
|
37
440
|
|
|
38
|
-
|
|
39
|
-
- [Okendo Shopify Hydrogen Demo Project](https://bitbucket.org/okendo/okendo-shopify-hydrogen-demo/)
|
|
441
|
+
## View Our Okendo Sample Hydrogen App <a id="view-our-okendo-sample-hydrogen-app" name="view-our-okendo-sample-hydrogen-app"></a>
|
|
40
442
|
|
|
41
|
-
|
|
443
|
+
We have created a Shopify Hydrogen sample application with our widgets pre-installed.
|
|
42
444
|
|
|
43
|
-
-
|
|
44
|
-
- Susanne Peng - susanne.peng@okendo.io
|
|
45
|
-
- Rowan Puckeridge - rowan.puckeridge@okendo.io
|
|
445
|
+
- [View our Sample Okendo Shopify Hydrogen Demo Repository](https://github.com/okendo/okendo-shopify-hydrogen-demo)
|