Skip to content

Latest commit

 

History

History
98 lines (66 loc) · 5.41 KB

README.md

File metadata and controls

98 lines (66 loc) · 5.41 KB
Raw

monarch

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

npm version

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)