Skip to content

Commit 1470ce1

Browse files
jcalcabentjwiebell
jcalcaben
authored and
tjwiebell
committed
Revise the README file (#21)
The README file has been re-written to link to the instructions for installation. The file now contains a description of the module and how to configure the module through the admin.
1 parent 5fec821 commit 1470ce1

File tree

1 file changed

+21
-192
lines changed

1 file changed

+21
-192
lines changed

‎README.md

Lines changed: 21 additions & 192 deletions
Original file line numberDiff line numberDiff line change
@@ -1,211 +1,40 @@
1-
# How to install UPWARD with a PWA Studio storefront
1+
# Magento 2 UPWARD connector module
22

3-
## Prerequisites
3+
The Magento 2 UPWARD connector is a module for routing requests to [UPWARD-PHP][].
4+
This module replaces the default Magento frontend theme with a PWA Studio storefront application.
45

5-
- An existing Magento Cloud project
6-
- Composer
7-
- Yarn or NPM
8-
- A [Magento PWA Studio][] storefront managed by NPM or Yarn.
6+
PWA Studio storefront deployments in the Magento Commerce Cloud use this module to keep Magento and storefront code on the same server.
97

10-
You are not required to publish to npmjs.com, but
11-
NPM or Yarn should be able to access your project code through Git.
8+
## Installation
129

13-
For this tutorial, the [`@magento/venia-concept`][] package for the [Venia storefront][] is used, but any PWA available though NPM with an UPWARD compatible YAML file is supported.
10+
The Magento 2 UPWARD connector module is part of the [Magento Cloud deployment][] steps in the official PWA Studio docs.
1411

15-
## Add node package dependency
12+
## Configuration
1613

17-
If it does not exist, [create a `package.json`][] file in your project directory.
14+
The Magento 2 UPWARD connector is configured in the admin area under:
1815

19-
```sh
20-
npm init -y
21-
```
22-
23-
Add your PWA Studio storefront to the list of dependencies in this file.
24-
25-
```json
26-
{
27-
"dependencies": {
28-
"@magento/venia-concept": "~2.0.0"
29-
}
30-
}
31-
```
32-
33-
## Add Composer dependencies
34-
35-
Add the repository information for the UPWARD PHP server and UPWARD Connector to the `repositories` section in your `composer.json`.
16+
**Stores > Configuration > General > Web > UPWARD PWA Configuration**.
3617

37-
```json
38-
"upward-connector": {
39-
"type": "vcs",
40-
"url": "https://github.com/magento-research/magento2-upward-connector"
41-
},
42-
"upward-php": {
43-
"type": "vcs",
44-
"url": "https://github.com/magento-research/upward-php"
45-
}
46-
```
47-
48-
To have composer install these packages, add them to the `require` section of the `composer.json` file.
49-
50-
```json
51-
"magento/module-upward-connector": "^1.0.0",
52-
"magento/upward": "^1.0.0"
53-
```
18+
### UPWARD Config File
5419

55-
## Add Venia sample data (optional)
56-
57-
The Venia storefront works best with the Venia sample data installed. There is an [automated script](https://magento-research.github.io/pwa-studio/venia-pwa-concept/install-sample-data/) in the `@magento/venia-concept` package, or you can follow the manual steps here.
58-
59-
If you are deploying your own custom storefront, you may skip this step and continue to the next section.
60-
61-
### Add sample data repository information
62-
63-
Add the Venia sample data repository information to the `repositories` section of the `composer.json` file.
64-
65-
```json
66-
"catalog-venia": {
67-
"type": "vcs",
68-
"url": "https://github.com/PMET-public/module-catalog-sample-data-venia"
69-
},
70-
"configurable-venia": {
71-
"type": "vcs",
72-
"url": "https://github.com/PMET-public/module-configurable-sample-data-venia"
73-
},
74-
"customer-venia": {
75-
"type": "vcs",
76-
"url": "https://github.com/PMET-public/module-customer-sample-data-venia"
77-
},
78-
"sales-venia": {
79-
"type": "vcs",
80-
"url": "https://github.com/PMET-public/module-sales-sample-data-venia"
81-
},
82-
"tax-venia": {
83-
"type": "vcs",
84-
"url": "https://github.com/PMET-public/module-tax-sample-data-venia"
85-
},
86-
"media-venia": {
87-
"type": "vcs",
88-
"url": "https://github.com/PMET-public/sample-data-media-venia"
89-
},
90-
```
20+
This configuration is the location of the UPWARD configuration file for the UPWARD-PHP server.
9121

92-
### Require the sample data modules
22+
_Use the absolute path on the server for the value of this configuration._
9323

94-
Add the sample data modules to the `require` section of the `composer.json` file to install them into Magento.
24+
Example: `/app/node_modules/@magento/venia-concept/dist/upward.yml`
9525

96-
```json
97-
"magento/module-catalog-sample-data-venia": "dev-master",
98-
"magento/module-configurable-sample-data-venia": "dev-master",
99-
"magento/module-customer-sample-data-venia": "dev-master",
100-
"magento/module-sales-sample-data-venia": "dev-master",
101-
"magento/module-tax-sample-data-venia": "dev-master",
102-
"magento/sample-data-media-venia": "dev-master",
103-
```
26+
### Front Name Whitelist
10427

105-
## Modify `.gitignore` file
28+
This configuration allows you to specify a line-separated list of routes to forward to the default Magento theme.
10629

107-
Add the following frontend dependency entries to the `.gitignore` file to track them in your repository.
30+
Example:
10831

10932
```text
110-
!package.json
111-
!yarn.lock
33+
contact
34+
privacy-policy-cookie-restriction-mode
11235
```
11336

114-
## Install dependencies
115-
116-
### Frontend dependencies
117-
118-
Install the frontend dependencies specified in the `package.json` file.
119-
120-
```sh
121-
yarn install
122-
```
123-
124-
A successful installation creates a `yarn.lock` file in your project directory.
125-
126-
### Composer dependencies
127-
128-
Install the new Composer dependencies added to the `composer.json` file.
129-
130-
```sh
131-
composer update
132-
```
133-
134-
## Specify Cloud server environment
135-
136-
### Install Yarn
137-
138-
If your project uses Yarn, which is the case for `venia-concept`, add the following entry to the `.magento.app.yaml` file.
139-
140-
```yaml
141-
dependencies:
142-
nodejs:
143-
yarn: "*"
144-
```
145-
146-
### Update build hooks
147-
148-
The `venia-concept` storefront uses a newer version of Node than the default environment provides.
149-
It also uses Yarn to install its dependencies.
150-
151-
The following update to the `hooks.build` section of `.magento.app.yaml` installs NVM, installs the latest LTS release of Node, and uses Yarn to install the project dependencies.
152-
153-
```yaml
154-
hooks:
155-
# We run build hooks before your application has been packaged.
156-
build: |
157-
set -e
158-
159-
unset NPM_CONFIG_PREFIX
160-
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | dash
161-
export NVM_DIR="$HOME/.nvm"
162-
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
163-
nvm install --lts=dubnium
164-
165-
yarn install
166-
167-
php ./vendor/bin/ece-tools build:generate
168-
php ./vendor/bin/ece-tools build:transfer
169-
```
170-
171-
### Add required environment variables
172-
173-
Use the Magento Cloud GUI or modify the `variables.env` entry in `.magento.app.yaml` to add any required environment variables.
174-
175-
The following table lists the required environment variables for the Venia storefront:
176-
177-
| Name | Value |
178-
| ------------------------------------------------------- | ----------------------------------------------------------- |
179-
| `CONFIG__DEFAULT__WEB__UPWARD__PATH` | `/app/node_modules/@magento/venia-concept/venia-upward.yml` (absolute path to UPWARD YAML configuration) |
180-
| `NODE_ENV` | `production` |
181-
| `MAGENTO_BACKEND_URL` | `https://[your-cloud-url-here]` |
182-
| `USE_FASTLY` | `0 / 1` (dependent on Cloud environment) |
183-
| `BRAINTREE_TOKEN` | `<generated token from Braintree>` |
184-
185-
## Commit modified files
186-
187-
Commit all changes to the following files:
188-
189-
- `.gitignore`
190-
- `.magento.app.yaml`
191-
- `composer.json`
192-
- `composer.lock`
193-
- `package.json`
194-
- `yark.lock`
195-
196-
If any of these files fails to add, check your `.gitignore` file.
197-
198-
## Push changes
199-
200-
Push your local changes for your deployment and wait for it to complete.
201-
202-
## Congratulations!
203-
204-
You have installed a PWA storefront on the Cloud.
205-
206-
You should be able to navigate to your Cloud instance and see your storefront.
37+
With this example, when a visitor navigates to either `<Magento store URL>/contact` or `<Magento store URL>/privacy-policy-cookie-restriction-mode`, they will land on a page rendered by Magento instead of the storefront application.
20738

208-
[magento pwa studio]: http://pwastudio.io
209-
[`@magento/venia-concept`]: https://www.npmjs.com/package/@magento/venia-concept
210-
[venia storefront]: https://magento-research.github.io/pwa-studio/venia-pwa-concept/
211-
[create a `package.json`]: https://docs.npmjs.com/cli/init
39+
[upward-php]: https://github.com/magento-research/upward-php
40+
[magento cloud deployment]: http://pwastudio.io/tutorials/cloud-deploy/

0 commit comments

Comments
 (0)