From 168ddb95b295bb45f1389cf94cfd542585ddd831 Mon Sep 17 00:00:00 2001 From: dominikgilg <74245822+dominikgilg@users.noreply.github.com> Date: Wed, 18 Jan 2023 15:55:25 +0100 Subject: [PATCH] CT-170 Creating readme with docs (#5) * created readme with docs --- README.md | 296 ++++++++++++++++++++++++++++++++++++++++++++++++++- package.json | 2 +- 2 files changed, 296 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7506a11..5eece84 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,299 @@ # @nosto/shopify-hydrogen +- `@nosto/shopify-hydrogen` is a React component library to implement Nosto within Shopify Hydrogen apps. +- You can check our [Hydrogen demo store](https://github.com/Nosto/shopify-hydrogen-demo) to see this library implemented in an actual Hydrogen project. + > :warning: This project is a work-in-progress and is not yet considered as production-ready. Full functionality will be achieved in our 1.0.0 release planned in Q1/2023. -`@nosto/shopify-hydrogen` is a React component library to implement Nosto within Shopify Hydrogen. +## Installation + +To install the package into your project, run: + +```sh +npm install @nosto/shopify-hydrogen +``` + +Or if you prefer using Yarn: + +```sh +yarn add @nosto/shopify-hydrogen +``` + +## Usage + +### Adding the plugin + +The first step is to import the Nosto plugin into `vite.config.js` in the root of your Hydrogen project and add it to the plugins array inside the configuration: + +```js +// vite.config.js + +import {defineConfig} from 'vite'; +import hydrogen from '@shopify/hydrogen/plugin'; +import nosto from '@nosto/shopify-hydrogen/plugin'; + +export default defineConfig({ + plugins: [hydrogen(), nosto()], + ... +}) +``` + +### Adding components + +The library uses [@nosto/nosto-react](https://github.com/Nosto/nosto-react) under the hood combined with Hydrogen specific hooks and functionality. You can import the following components: + +#### NostoProvider + +- The NostoProvider component is **required** and provides the Nosto functionality. +- It must wrap all other Nosto components. +- Pass your Nosto merchant ID via the `account` prop. + +```jsx +// src/App.server.jsx + +import { NostoProvider } from "@nosto/shopify-hydrogen"; + +function App() { + return ( + + + + + + } /> + + + + + ); +} +``` + +#### NostoSession + +- The NostoSession component syncs customer data and the shopping cart with Nosto. +- No props required, the component handles the whole functionality and interacts with Nosto automatically. + +```jsx +// src/App.server.jsx + +import { NostoProvider, NostoSession } from "@nosto/shopify-hydrogen"; + +function App() { + return ( + + + + + + } /> + + + + + + + ); +} +``` + +#### NostoPlacement + +- The NostoPlacement component renders a static Nosto placement. +- Pass the placement id via the `id` prop. + +```jsx +import { NostoPlacement } from "@nosto/shopify-hydrogen"; + +; +``` + +#### NostoHome + +- The NostoHome component needs to be added on the home/front page. +- It loads the campaigns for all the Nosto placements on the page. +- No props required. +- Must be rendered as last of all Nosto components on the page. + +```jsx +// src/routes/index.server.jsx + +import { NostoHome, NostoPlacement } from "@nosto/shopify-hydrogen"; + +function HomepageContent() { + return ( + <> + ... + + + + + ); +} +``` + +#### NostoProduct + +- The NostoProduct component needs to be added on product pages. +- It loads the campaigns for all the Nosto placements on the page. +- Pass the product id via the `product` prop +- For Nosto tagging pass the product data via the `tagging` prop +- Must be rendered as last of all Nosto components on the page. + +```jsx +// src/routes/products/[handle].server.jsx + +import { NostoProduct, NostoPlacement } from '@nosto/shopify-hydrogen'; + +export default function Product() { + + ... + const {media, title, vendor, descriptionHtml, id, productType} = product; + + let nostoProductId = id.split('/')?.at(-1); + + return ( + + + ... + + + + + + ); +} +``` + +#### NostoCategory + +- The NostoCategory component needs to be added on collection pages. +- It loads the campaigns for all the Nosto placements on the page. +- Pass the collection title via the `category` prop. +- Must be rendered as last of all Nosto components on the page. + +```jsx +// src/routes/collections/[handle].server.jsx + +import { NostoCategory, NostoPlacement } from "@nosto/shopify-hydrogen"; + +export default function Collection() { + return ( + + ... + + + + + ); +} +``` + +#### NostoSearch + +- The NostoSearch component needs to be added on the search page. +- It loads the campaigns for all the Nosto placements on the page. +- Pass the search term via the `query` prop. +- Must be rendered as last of all Nosto components on the page. + +```jsx +// src/routes/search.server.jsx + +import { NostoSearch, NostoPlacement } from "@nosto/shopify-hydrogen"; + +export default function Search() { + const { searchParams } = useUrl(); + const searchTerm = searchParams.get("q"); + + return ( + +
+ ... + + + +
+ + ); +} +``` + +#### NostoOther + +- The NostoOther component needs to be added on pages with no specific page type. +- It loads the campaigns for all the Nosto placements on the page. +- No props required. +- Must be rendered as last of all Nosto components on the page. + +```jsx +import { NostoOther, NostoPlacement } from "@nosto/shopify-hydrogen"; + +function OtherPage() { + return ( + <> + ... + + + + + ); +} +``` + +#### NostoCheckout + +- The NostoCheckout component needs to be added on the cart page. +- It loads the campaigns for all the Nosto placements on the page. +- No props required. +- Must be rendered as last of all Nosto components on the page. + +```jsx +// src/components/global/NotFound.server.jsx + +import { NostoCheckout, NostoPlacement } from "@nosto/shopify-hydrogen"; + +export default function Cart() { + return ( + + ... + + + + + ); +} +``` + +#### Nosto404 + +- The Nosto404 component needs to be added on 404/not found pages. +- It loads the campaigns for all the Nosto placements on the page. +- No props required. +- Must be rendered as last of all Nosto components on the page. + +```jsx +// src/components/global/NotFound.server.jsx + +import { NostoOther, NostoPlacement } from "@nosto/shopify-hydrogen"; + +export function NotFound() { + return ( + + ... + + + + + ); +} +``` + +## Authors + +- **Dominik Gilg** - [dominikgilg](https://github.com/dominikgilg) + +See also the list of [contributors](https://github.com/Nosto/shopify-hydrogen/contributors) who participated in this project. + +## License + +MIT License © Nosto Solutions diff --git a/package.json b/package.json index 37c787e..9cce875 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ "shopify", "hydrogen" ], - "version": "0.3.0", + "version": "0.4.0", "files": [ "dist", "src"