137 lines
5.3 KiB
Markdown
137 lines
5.3 KiB
Markdown
## The node.js example app
|
||
|
||
The node.js example app teaches the very basics of how to work with Contentful:
|
||
|
||
- consume content from the Contentful Delivery and Preview APIs
|
||
- model content
|
||
- edit content through the Contentful web app
|
||
|
||
The app demonstrates how decoupling content from its presentation enables greater flexibility and facilitates shipping higher quality software more quickly.
|
||
|
||
<a href="https://the-example-app-nodejs.herokuapp.com/" target="_blank"><img src="https://images.contentful.com/qz0n5cdakyl9/4GZmvrdodGM6CksMCkkAEq/700a527b8203d4d3ccd3c303c5b3e2aa/the-example-app.png" alt="Screenshot of the example app"/></a>
|
||
|
||
You can see a hosted version of `The node.js example app` on <a href="https://the-example-app-nodejs.herokuapp.com/" target="_blank">Heroku</a>.
|
||
|
||
## What is Contentful?
|
||
Contentful is content infrastructure for web applications, mobile apps and connected devices. It allows you to create, edit and manage content in the cloud and publish it anywhere via powerful APIs. Contentful offers tools for editorial teams and enabling cooperation between organizations.
|
||
|
||
## Requirements
|
||
|
||
* Node 8
|
||
* Git
|
||
* Contentful CLI (only for write access)
|
||
|
||
Without any changes, this app is connected to a Contentful space with read-only access. To experience the full end-to-end Contentful experience, you need to connect the app to a Contentful space with read _and_ write access. This enables you to see how content editing in the Contentful web app works and how content changes propagate to this app.
|
||
|
||
## Common setup
|
||
You can clone the space for this example app to your own Contentful account by using our CLI tool.
|
||
|
||
```
|
||
contentful space seed -s '<SPACE_ID>' -t the-example-app
|
||
```
|
||
|
||
If you do not have the Contentful CLI installed you can find instructions on installation and usage [here](https://www.npmjs.com/package/contentful-cli). For more information on the content model check out [this repo](https://github.com/contentful/content-models/tree/master/the-example-app/README.md).
|
||
|
||
Once you’ve created a space, you can change the credentials in the variables.env. If you don’t feel like changing code immediately, you can also inject credentials via url parameters like so:
|
||
|
||
Clone the repo and install the dependencies.
|
||
|
||
```bash
|
||
git clone https://github.com/contentful/the-example-app.nodejs.git
|
||
```
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
## Steps for read-only access
|
||
|
||
To start the express server, run the following
|
||
|
||
```bash
|
||
npm run start:dev
|
||
```
|
||
|
||
Open [http://localhost:3000](http://localhost:3000) and take a look around.
|
||
|
||
|
||
## Steps for read and write access (recommended)
|
||
|
||
Step 1: Install the [Contentful CLI](https://www.npmjs.com/package/contentful-cli)
|
||
|
||
Step 2: Login to Contentful through the CLI. It will help you to create a [free account](https://www.contentful.com/sign-up/) if you don't have one already.
|
||
```
|
||
contentful login
|
||
```
|
||
Step 3: Create a new space
|
||
```
|
||
contentful space create --name 'My space for the example app'
|
||
```
|
||
Step 4: Seed the new space with the content model. Replace the `SPACE_ID` with the id returned from the create command executed in step 3
|
||
```
|
||
contentful space seed -s '<SPACE_ID>' -t the-example-app
|
||
```
|
||
Step 5: Head to the Contentful web app's API section and grab `SPACE_ID`, `DELIVERY_ACCESS_TOKEN`, `PREVIEW_ACCESS_TOKEN`.
|
||
|
||
Step 6: Open `variables.env` and inject your credentials so it looks like this
|
||
|
||
```
|
||
NODE_ENV=development
|
||
CONTENTFUL_SPACE_ID=<SPACE_ID>
|
||
CONTENTFUL_DELIVERY_TOKEN=<DELIVERY_ACCESS_TOKEN>
|
||
CONTENTFUL_PREVIEW_TOKEN=<PREVIEW_ACCESS_TOKEN>
|
||
PORT=3000
|
||
```
|
||
|
||
Step 7: To start the express server, run the following
|
||
```bash
|
||
npm run start:dev
|
||
```
|
||
Final Step:
|
||
|
||
Open [http://localhost:3000?enable_editorial_features](http://localhost:3000?enable_editorial_features) and take a look around. This URL flag adds an “Edit” button in the app on every editable piece of content which will take you back to Contentful web app where you can make changes. It also adds “Draft” and “Pending Changes” status indicators to all content if relevant.
|
||
|
||
## Deploy to Heroku
|
||
You can also deploy this app to Heroku:
|
||
|
||
[](https://heroku.com/deploy)
|
||
|
||
Open [http://localhost:3000?enable_editorial_features](http://localhost:3000?enable_editorial_features) and take a look around. This URL flag adds an “Edit” button in the app on every editable piece of content which will take you back to Contentful web app where you can make changes. It also adds “Draft” and “Pending Changes” status indicators to all content if relevant.
|
||
|
||
## Deploy to Heroku
|
||
You can also deploy this app to Heroku:
|
||
|
||
[](https://heroku.com/deploy)
|
||
|
||
|
||
## Use Docker
|
||
You can also run this app as a Docker container:
|
||
|
||
Step 1: Clone the repo
|
||
|
||
```bash
|
||
git clone https://github.com/contentful/the-example-app.nodejs.git
|
||
```
|
||
|
||
Step 2: Build the Docker image
|
||
|
||
```bash
|
||
docker build -t the-example-app.nodejs .
|
||
```
|
||
|
||
Step 3: Run the Docker container locally:
|
||
|
||
```bash
|
||
docker run -p 3000:3000 -d the-example-app.nodejs
|
||
```
|
||
|
||
If you created your own Contentful space, you can use it by overriding the following environment variables:
|
||
|
||
```bash
|
||
docker run -p 3000:3000 \
|
||
-e CONTENTFUL_SPACE_ID=<SPACE_ID> \
|
||
-e CONTENTFUL_DELIVERY_TOKEN=<DELIVERY_ACCESS_TOKEN> \
|
||
-e CONTENTFUL_PREVIEW_TOKEN=<PREVIEW_ACCESS_TOKEN> \
|
||
-d the-example-app.nodejs
|
||
```
|