Skip to content

Commit 64ec14c

Browse files
markbrocatomarkbrocato
authored
Merge pull request #10 from storefront-foundation/ianand-magento2-readme-update
Updated Magento 2 connector README
2 parents d20d6d9 + 983dec2 commit 64ec14c

File tree

1 file changed

+38
-119
lines changed

1 file changed

+38
-119
lines changed

‎README.md‎

Lines changed: 38 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,159 +1,78 @@
11
# Magento 2 Connector
22

3-
[Adobe Magento 2](https://devdocs.magento.com/guides/v2.3/graphql/) connector for [React Storefront](https://github.com/storefront-foundation/react-storefront).
3+
The [React Storefront](https://github.com/storefront-foundation/react-storefront) headless ecommerce connector for [Adobe Magento 2](https://devdocs.magento.com/guides/v2.3/graphql/).
44

5-
## Requirements
5+
This guide covers how to get up and running with the Magento 2 Connector. For information on connectors in general and how to write your own connector refer to the [React Storefront Connectors](https://docs.reactstorefront.io/guides/connectors) documentation.
66

7-
`M2_CONFIG_HOST` Node.js Environment Variable defining your origin site based on Magento 2.
7+
## Requirements
88

9-
See `.env.sample` file as an example of adding env variable via [dotenv](https://www.npmjs.com/package/dotenv). You can also check [this guide](https://www.twilio.com/blog/working-with-environment-variables-in-node-js-html) to get more info about Node.js Environment Variables.
9+
You will need a Magento 2 (sometimes referred to as "M2") backend to try out the connector.
1010

11-
## Usage
11+
## Running Locally
1212

13-
Initialize config environment variables by using
13+
Create a new React Storefront app using version 8.14.0 or later:
1414

15-
```js
16-
require('dotenv').config()
1715
```
18-
19-
in one of your server files (for example `server.js` in NextJS).
20-
21-
Then, you can simply import normalizer and fetch helper in your backend handlers.
22-
23-
### Product data:
24-
25-
```js
26-
import { fetchProduct, normalizeProduct } from 'react-storefront-magento2-connector/product';
27-
...
28-
29-
const rawProduct = await fetchProduct(productId);
30-
// normalize it for React Storefront https://docs.reactstorefront.io/guides/product
31-
const product = normalizeProduct(rawProduct, productId);
16+
npm create react-storefront@^8.014.0 my-m2-app
3217
```
3318

34-
### Product reviews:
19+
Next `cd` into your created application and install the Magento2 connector:
3520

36-
```js
37-
import fetchProductReviews from 'react-storefront-magento2-connector/product/reviews/fetchProductReviews';
38-
...
39-
// Magento API returns HTML as result for reviews, so no need to normalize the data
40-
const data = await fetchProductReviews(productId);
41-
...
4221
```
43-
44-
### CMS slots:
45-
46-
```js
47-
import { fetchCmsBlocks, normalizeCmsBlocks } from 'react-storefront-magento2-connector/cms/blocks';
48-
...
49-
// identifiers is a string with CMS block id
50-
const rawData = await fetchCmsBlocks({ identifiers });
51-
const data = normalizeCmsBlocks(rawData);
52-
...
22+
cd my-m2-app
23+
npm install react-storefront-magento2-connector
5324
```
5425

55-
### Search
26+
Next configure the `M2_CONFIG_HOST` environment variable in `.env` file to point to your Magento2 backend. See `.env.sample` file as an example of adding env variable via [dotenv](https://www.npmjs.com/package/dotenv). You can also check [this guide](https://www.twilio.com/blog/working-with-environment-variables-in-node-js-html) to get more info about Node.js Environment Variables. For example, your `.env` file may look like:
5627

57-
```js
58-
import { fetchSearch, normalizeSearch } from 'react-storefront-magento2-connector/search';
59-
...
60-
// where "search" is a search term
61-
const rawData = await fetchSearch({ search });
62-
// normalize it to follow React Storefront data contract https://docs.reactstorefront.io/guides/search
63-
const data = normalizeSearch(rawData);
64-
...
6528
```
66-
67-
### Subcategory
68-
69-
#### Subcategory data
70-
71-
```js
72-
import { fetchSubcategory, normalizeSubcategory } from 'react-storefront-magento2-connector/subcategory';
73-
...
74-
const rawData = await fetchSubcategory({ categoryId });
75-
// normalize data to follow React Storefront data contract https://docs.reactstorefront.io/guides/subcategory
76-
const { id, name } = normalizeSubcategory(rawData);
29+
LEGACY_BACKEND_DOMAIN=www.my-magento-site.com
30+
LEGACY_BACKEND_HOST_HEADER=www.my-magento-site.com
31+
M2_CONFIG_HOST=http://www.my-magento-site.com
7732
```
7833

79-
#### Subcategory id by URL key
80-
81-
```js
82-
import { fetchSubcategoryId, normalizeSubcategoryId } from 'react-storefront-magento2-connector/subcategory/id';
83-
...
84-
const rawData = await fetchSubcategoryId({ urlKey });
85-
const id = normalizeSubcategoryId(rawData);
86-
...
87-
```
34+
Finally set the connector in your `next.config.js` file. By default this file is set to use the `react-storefront/mock-connector` as shown below:
8835

89-
#### Nested subcategories by URL key
90-
91-
```js
92-
import {
93-
fetchSubcategorySubCategories,
94-
normalizeSubcategorySubCategories,
95-
} from 'react-storefront-magento2-connector/subcategory/sub-categories';
96-
...
97-
const rawData = await fetchSubcategorySubCategories({ urlKey });
98-
const data = normalizeSubcategorySubCategories(rawData);
99-
...
10036
```
37+
module.exports = withReactStorefront({
10138
102-
### Menu
39+
// ... Some code
40+
41+
connector: 'react-storefront/mock-connector',
10342
104-
```js
105-
import { fetchMenu, normalizeMenu } from 'react-storefront-magento2-connector/menu';
106-
...
107-
const rawData = await fetchMenu({});
108-
const data = normalizeMenu(rawData);
109-
...
43+
// ... More code
11044
```
11145

112-
### Helpers:
46+
Change this line to use the `react-storefront-magento2-connector` as shown below:
11347

114-
Catch / properly handle error message from GraphQL response
48+
```
49+
module.exports = withReactStorefront({
11550
116-
```js
117-
import getError from 'react-storefront-magento2-connector/helpers/getError';
118-
...
119-
const rawData = await fetchProduct(productId);
51+
// ... Some code
52+
53+
connector: 'react-storefront-magento2-connector',
12054
121-
const error = getError(rawData);
122-
if (error) {
123-
return {
124-
error,
125-
};
126-
}
55+
// ... More code
12756
```
12857

129-
### Cart
130-
131-
[Add to cart](examples/next/cart/common/addToCart.js)
58+
Now you can run your project locally,
13259

133-
[Merge carts](examples/next/cart/common/mergeCarts.js)
60+
```
61+
npm start
62+
```
13463

135-
[Create customer](examples/next/cart/customer/createCustomer.js)
64+
And then visit http://127.0.0.1:3000 in your browser.
13665

137-
[Generate token](examples/next/cart/customer/generateToken.js)
66+
## Deploying to the Moovweb XDN
13867

139-
[Revoke token](examples/next/cart/customer/revokeToken.js)
68+
The front-end React Storefront can be hosted anywhere that supports Node and Express but it works great on the [Moovweb XDN](https://www.moovweb.com/). You can try the XDN for free by signing up [here](https://moovweb.app/signup?redirectTo=/). Once you have an account you can deploy it by running `xdn deploy`:
14069

141-
[Guest cart](examples/next/cart/guest/cart.js)
70+
```
71+
xdn deploy
72+
```
14273

143-
[Obtain session / create empty cart](examples/next/cart/guest/obtainSession.js)
74+
Refer to the [XDN deployment guide](https://developer.moovweb.com/guides/deploying) for more information.
14475

145-
#### Get cart data
14676

147-
```js
148-
import { fetchCart, normalizeCart } from 'react-storefront-magento2-connector/cart/customer/cart';
149-
...
150-
const rawData = await fetchCart(token);
151-
const data = normalizeCart(rawData);
152-
...
153-
```
15477

155-
## Examples
15678

157-
- See `/examples/react/` for [ReactJS](https://reactjs.org/) stuff examples
158-
- See `/examples/rsf/` for [React Storefront](https://github.com/storefront-foundation/react-storefront) handlers examples
159-
- See `/examples/next/` for [NextJS](https://nextjs.org/) handlers examples (they are also can be used in RSF v7+)

0 commit comments

Comments
 (0)