# @xolvio/contentful-pipelines

> ## How to Install

Latest version **1.2.2** (published 2021-11-10) · 0 weekly downloads

## Install

```sh
npm install @xolvio/contentful-pipelines
pnpm add @xolvio/contentful-pipelines
yarn add @xolvio/contentful-pipelines
bun add @xolvio/contentful-pipelines
```

Provides the command `xolvio-contentful-migrations`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2021-11-10 |
| First published | 2020-06-21 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 50.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | cwohlman, samhatoum, lgandecki, dweller23, bombellos |

## Links

- npm: https://www.npmjs.com/package/@xolvio/contentful-pipelines
- npm.io page: https://npm.io/package/@xolvio/contentful-pipelines

## Dependencies (5)

- [glob](https://npm.io/package/glob.md) ^7.1.7
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0
- [dateformat](https://npm.io/package/dateformat.md) ^4.5.1
- [micromatch](https://npm.io/package/micromatch.md) ^4.0.4
- [contentful-migrate](https://npm.io/package/contentful-migrate.md) ^0.16.0

## Recent versions

- 1.2.2 (latest) — 2021-11-10
- 1.2.1 — 2021-11-08
- 1.2.0 — 2021-08-05
- 1.1.0 — 2021-08-05
- 1.0.0 — 2021-08-04
- 0.1.2 — 2020-06-21
- 0.1.1 — 2020-06-21
- 0.1.0 — 2020-06-21

## README

# Contentful Pipelines

## How to Install

```
npm -D install @xolvio/contentful-pipelines
```

## API

The `contentful pipelines` package exposes two commands which can be run either as a `package.json` script or executed in the code (runtime).

#### Migrations
Given directory structure:

```
your-project
├── README.md
├── src
│   └── components
│       ├── Title
│       │    └── migrations
│       │         └── title
│       │               └── 1513695986378-create-title-type.js
│       └── Sections
│            └── migrations
│                 └── sections
│                       └── 1513695986378-create-title-type.js
├── package.json

```

Running as `package.json` command:

```shell script
"migrations": "CONTENTFUL_MANAGEMENT_API=<contentful-management-api-key> CONTENTFUL_SPACE_ID=<contentful-space-id> CONTENTFUL_ENVIRONMENT_ID=<contentful-environment-id> xolvio-contentful-migrations src/components/Title src/components/Sections"
```

Running from code:

```typescript
async function runMigrations(migrationPaths, options);
```

| Parameter        | Type                                                                                                         | Default                                                                                                                                                                                     | Description                                                                                                                 |
| :--------------- | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
| `migrationPaths` | `string[]`                                                                                                   | []                                                                                                                                                                                          | **Required**. List of paths to the components containing migration scripts. Paths should be relative to the project's root. |
| `options`        | {<br>targetEnvironment: `string`,<br><br>spaceId: `string`,<br><br>contentfulManagementApiKey: `string`<br>} | `targetEnvironment = process.env.CONTENTFUL_ENVIRONMENT_ID` <br><br>`spaceId = process.env.CONTENTFUL_SPACE_ID`<br><br>`contentfulManagementApiKey = process.env.CONTENTFUL_MANAGEMENT_API` | Optional. Overwrites the `process.env` variables                                                                            |

```typescript
const { runMigrations } = require("@xolvio/contentful-pipelines");

await runMigrations(["src/components/Title", "src/components/Sections"]);
```

#### Creating the contentful environment
Running as `package.json` command:

```shell script
"createQaEnvironmentFromProd": "CONTENTFUL_MANAGEMENT_API=<contentful-management-api-key> CONTENTFUL_SPACE_ID=<contentful-space-id> CONTENTFUL_SOURCE_ENVIRONMENT=<contentful-prod-environment-id> CONTENTFUL_ENVIRONMENT_ID=<contentful-environment-id> xolvio-contentful-create-environment"
```

Running from code:

```typescript
async function createEnvironmentFromSource(options);
```

| Parameter | Type                                                                                                                                             | Default                                                                                                                                                                                                                                                          | Description                                      |
| :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
| `options` | {<br>sourceEnvironment: `string`,<br><br>targetEnvironment: `string`,<br><br>spaceId: `string`,<br><br>contentfulManagementApiKey: `string`<br>} | `sourceEnvironment=process.env.CONTENTFUL_SOURCE_ENVIRONMENT`<br><br>`targetEnvironment = process.env.CONTENTFUL_ENVIRONMENT_ID` <br><br>`spaceId = process.env.CONTENTFUL_SPACE_ID`<br><br>`contentfulManagementApiKey = process.env.CONTENTFUL_MANAGEMENT_API` | Optional. Overwrites the `process.env` variables |

Example:

```typescript
await createEnvironmentFromSource();
```

## Writing migration scripts
For executing the migrations we're using [Contentful Migrate Tool](https://github.com/deluan/contentful-migrate) so the migrations are written using their syntax. Using their CLI tool you can quickly create the migration scripts based on the existing Contentful Content Types.

#### Useful scripts
Fetch existing entry data (used for initial data migration scripts)

```typescript
module.exports.up = async (migration, { makeRequest }) => {
  const existing = await makeRequest({
    method: "GET",
    url: `/entries/ENTRY_ID_TO_QUERY`,
  }).catch(console.log);

  console.log("existing: ", JSON.stringify(existing.fields));
};
```

Create contentful entry from within the contentful migration script:

```typescript
module.exports.up = async (migration, { makeRequest }) => {
  await makeRequest({
    method: "PUT",
    url: `/entries/NEW_ENTRY_ID`,
    data: EXISTING_FIELDS_FROM_SNIPPET_ABOVE,
    headers: {
      "X-Contentful-Content-Type": "CONTENT_TYPE_ID",
    },
  });
};
```
## TODO
- CLI for running migrations for all of the components listed in the package.json

---
_Source: https://npm.io/package/@xolvio/contentful-pipelines · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._