wework/monarch

Creates Contentful migrations by mapping over React component proptypes

monarch

Welcome to Monarch! We offer a node script to allow you to dynamically create Contentful migration files within your application.

Getting Started

These docs reference the most current version. Since it is still in an alpha release, run the following to get the most recent release:

npm install -g @wework/monarch@next

Note: this tool uses the libraries contentful-migrate and react-docgen, to assist in parsing the React components and creating the initial migration directory

Parsing a React Component

Run:

monarch parse:react <path/to/component/file>

Check out migrations directory and see that the file has been created. If you run this script multiple times, you will see a new file for each time it is run, name spaced with the timestamp of creation.

For adding a content model description, use jsdoc comments above the component definition.

For ignoring proptypes or entire components, use jsdoc comment flag @ignore-content-type. See example here

Read about contentful content types.

Proptype specs:

Proptype	Contentful type	jsdoc flag required	Notes
string	Symbol
node	Symbol
oneOf	Symbol w/ predefined values
number	Number
bool	Boolean
arrayOf	Array		only supports Link types
object	Link to asset	@asset
object	Link
shape	Link to asset	@asset
shape	Link
func	null		ignored by default
instanceOf	null		ignored by default
prop name starts with _	null		ignored by default (ex. _id)

Reference validators:

We recommend using AirBnb's airbnb-prop-types for custom proptype validations, we support the following:

Validator	Contentful type	Notes
childrenOfType()	Link	to reference
childrenOfType()	Array of Links	needs @array jsdoc flag
componentWithName()	Link	to reference
componentWithName()	Array of Links	needs @array jsdoc flag

used like so:

ParentComponent.propTypes = {
  children: childrenOfType(Component),
  otherThing: componentWithName('OtherComponent'),
  /** @array */
  allThings: componentWithName('SingleComponent')
};

Parsing a raw object

If you'd rather translate a raw object (example of structure here) into a migration file, run:

monarch parse:raw <path/to/object/file>

Check out migrations directory and see that the file has been created. If you run this script multiple times, you will see a new file for each time it is run, name spaced with the timestamp of creation.

Running the migration files

Once you have the files generated, you are ready to push them up to Contentful!

1. Make sure your Contentful space has been initialized with a Migration content model. If you need to initialize a space, use command ctf-migrate init

2. Once initialized, run the migrations with commands ctf-migrate up to create the model & ctf-migrate down to delete it.

Contributing

Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.

Troubleshooting

• error: No suitable component definition found.
  • this the component is exporting a connected component - if you export the component itself, this should fix this error (see reactjs/react-docgen#288)

monarch's Issues

add support for contentful-cli

some of the issues we've found so far with ctf-migrate that have been pretty annoying:

• no "real" down migrations. all entries need to be deleted before content-type can be deleted. (this doesn't matter if you're only doing "forward only migrations" i guess!)
• no rate limiter for api requests. so if you run a large amount of migrations it chokes
  and most recently (we wrote script to deal with these things)
• migrations just flat out stopped working a couple weeks ago possibly related to this issue: deluan/contentful-migrate#28, deluan has been slow to get pr for the fix merged.

from @sssyed 🙏

Adding support for contentful-cli (and/or deprecating support for ctf-migrate) may be needed - please look into this