Mozaik Javascript SDK

by Peter Balazs on 30/07/2018

One of our primary goals is to give the best tools and experience to developers. To make your work as productive as possible. This is why we've created an SDK and CLI tool that you can use for managing workspaces and projects either from custom scripts or using the command line. You can in install it from NPM and check the source code on Github.

What can you do with the SDK today?

The current SDK supports the principal basic operations in Mozaik. You can create content types, content type fields or import a full schema. You can create assets (but not by file uploads at the moment). And of course, you can create and publish documents. Although we know that this is not the full feature set that you have in the Mozaik App, we think it gives the minimal functionality to be able to set up a new project in a few minutes.

Installing the SDK

First, you have to install the SDK from the NPM registry:

npm install --save-dev @mozaikio/sdk or yarn add @mozaikio/sdk --dev

By adding it to your project's development dependencies, you will have access to both the SDK and the CLI tool.

The next step is to set the API endpoint for your project and the access key for authorization. You can do this by environment variables or a .mozaikrc config file placed in your project's root folder.

.mozaikrc file

The .mozaikrc config file can contain multiple config definitions. Each definition is a profile, and you can quickly switch between profiles by using the MOZAIK_PROFILE environment variable. When you don't set the MOZAIK_PROFILE, the SDK will try to use the default profile config values.

[default]
api_endpoint = "https://api.mozaik.io/graphql/your-project-name"
api_access_key = "your-access-key"

[other-project]
api_endpoint = "https://api.mozaik.io/graphql/other-project"
api_access_key = "your-access-key"

Environment variables

If you prefer to use environment variables, the SDK will look for the following two: MOZAIK_API_ENDPOINT and MOZAIK_API_ACCESS_KEY

Using the CLI

To use the CLI we recommend to create an NPM script in your package.json file:

...
"scripts": {
  "mozaikio": "mozaikio"
}
...

Using the CLI

After that, you can call it by running npm run mozaikio [command] or yarn mozaikio [command]

Currently, there are two commands available: the init and create

  • init: It creates a .mozaikrc file with the default profile (you will still need to set the values) and a mozaik-schema.graphql file that can be used to define a content type schema.
  • create: it creates a content type schema based on the mozaik-schema.graphql file

Defining your content type schema

You can define your content type schema with the GraphQL Schema Definition Language, by using the predefined scalars, interfaces and directives. We will cover this in the following blog post. Until then you can check the documentation on Github.

What's next?

In the following weeks, we will continuously add support for the existing API calls (updating content types, editing and scheduling documents, creating webhooks, etc.).

Also, we're working on the content type schema migration. You will be able to edit your existing mozaik-schema.graphql file and the SDK will create a migration plan that you can review and accept. With this, it will be trivial and safe to evolve your project's content type schema or migrate changes from a dev environment to staging or production. But more on this a bit later.

If you have any questions, feedback or feature requests, you can tell it to us know on Slack or by opening an issue in the Mozaik SDK repository.