@gjirafatech/codex NPM

Quick start

To start developing plugins you need to install codex toolkit which will help you creating the plugin structure and preview your plugins real-time on Codex admin.

Pre-requisites
Familiarity with the command line
Install Node.js version 15.0 or higher

Install codex toolkit

Start by installing codex toolkit on your machine by running the following command

npm install -g @gjirafatech/codex

Commands

Open your terminal and type codex --help or shorthand codex -h, if you see a list of commands and options you’re set and ready to use the CLI.

Create the plugin

To create a plugin using codex toolkit run the following command in the directory you want to create the plugin

codex create

This command will prompt you to choose where to host your Codex admin preview. You can choose between: 1. Cloud

Local

After choosing the host type, you will be prompted to choose what template for plugins you want to use. You can choose between:

Blank template
Sport template (from documentation)

Directory structure

root-directory

│ .codexignore

│ docker-compose.yaml

│ manifest.json

WARNING
.codexignore file contains the necessary data for the live preview of playground and it should not be modified otherwise your session in playground might not work as expected
docker-compose.yaml contains the necessary configurations for local hosting option. Overwriting any content of this file can cause problems with locally hosting Codex admin.

Environments

If no environment is selected by the user, Production will be set as the default environment. To select an environment pass the --environment flag or -e shorthand followed by an input of the desired environment, if you need to run commands on Testing environment your command should look something like this:

codex create -e Staging, after this command user will be prompted to insert an API Key for the specified environment.

If API Key is successfully validated, the default template will be initialized locally by writing all files on your current working directory. You can get your API key from Codex Admin intarface.

Manifest

The manifest.json file contains all the most important information about the plugin.

{

"pluginName": "weather",

"pluginDisplayName": "Weather",

"version": "1.0.0",

"widgets": [],

"routes": [],

"navigation": []

}

`pluginName`

A string that represents a unique name for the plugin.

`pluginDisplayName`

A string that represents a user friendly name that is goin to be displayed to the users in Codex.

`version`

A string that represents the version of the plugin, for example: '1.0.1'

`widgets`

A string that represents all the widgets that this plugin is adding in Codex.

`routes`

A string that represents all the routes and pages that this plugin is adding in Codex.

`navigaton`

A string that represents all the navigation menu items that this plugin is adding in Codex.

Playground

Codex provides an advanced playground environment which allows you to preview your plugins in the Codex admin. To start your Codex admin preview, run the following command in your terminal:

codex run

Cloud

If you have chosen the cloud hosting option, a new session will be created for you, which in background fires up a new instance of Codex admin in development mode explicitly for you, on cloud. For each session the playground generates a unique Codex admin domain, which allows you to live preview the plugins that you are developing in your local machine. Since the domain is public, you can also share it with others and see the changes on real-time.

https://se123sasd.playground.gjirafa.tech/

How does the cloud option work?

The codex cli tool handles the synchronization with Playground API and makes sure all your code is sent to your Codex admin instance to preview the changes.

The moment you run the codex run command the codex tool checks if you have created a session recently or create a new one.
The codex tool sends a request in the Playground API to fire up a new session for you for Codex admin preview.
The Playground API fires up the newest version of Codex admin with a custom domain for that session runs it on Codex infrastructure.
The codex tool watches for any change made in the files of the plugin directory and synchronizes all the changes with Playground API in near real-time.
The Playground API synchronizes all the changes with your Codex admin instance.
Since the Codex admin instance is run on development mode, you will see any changes you make being hot reloaded.

Local

If you have chosen the local hosting option, the session will be created locally on your machine, as a Docker container. For this option you will need to have Docker installed and running on your machine. We suggest DockerDesktop, since it makes it easier to install and run Docker. The Codex admin preview will be available on http://localhost:8080 for you to use and preview your changes. This option may be slower than the cloud option but offers better stability during development.

How does the local option work?

The codex cli tool handles the synchronization with Docker which is installed on your machine, and makes sure that your plugin files are mounted into the Docker container which contains the Codex admin preview locally.

The moment you run the codex run command, it checks if you have a session running. If not, it creates a new one for you.
The codex tool creates and starts the Docker container for Codex admin locally on port 8080.
If port 8080 is taken by another program, it will choose the next available port.
After that, the latest Codex admin image is pulled from our Docker registry, using our credentials.
If the image is being pulled for the first time, it may take a while until it downloads the entire Codex admin image. After the first time, the process of pulling the latest Codex admin image becomes a lot faster, thanks to Docker caching the unchanged layers of the image.
When Codex admin image is successfully pulled, the codex tool starts the Codex admin as a Docker container on your machine
The codex tool watches for any changes made in the files of the plugin directory and synchronizes all the files with your local Codex admin container.
Since the Codex admin instance is run on development mode, you will see any changes you make being hot reloaded.

Note
In addition to choosing the hosting type with codex create command when you create your plugin at the beginning, you can also switch between hosting types using the --host flag on the codex run command: codex run --host local or codex run --host cloud.
WARNING
Depending on your machine's performance, the compilation process when developing plugins locally using the local hosting type, may be slower than on cloud. This is because Docker runs as a Virtual Machine on Windows or MacOS, unless you use a Linux based OS.

Restart session

Codex also provides a command to restart your current session, which can be used when having issues with Admin live preview or other issues related to your running session.

codex restart

After running codex restart your Codex admin preview will be restarted and compiled from the beginning with your latest file changes. The flow of this command is similar to codex run command.

Delete/kill session

This is a command to delete your current session, whether it is running locally or on cloud. This command is useful when having unclear issues with your running session.

codex kill

After running codex kill your Codex admin preview will be deleted. To start your Codex admin preview again, you have to run the codex run command.

Publishing your plugin

When you finish working on your plugin, you can make a request to the Codex team to publish your plugin.

codex publish

This command sends your plugin to the Codex team, who will review it before releasing it for all the users of your organization.

Session creation
Since session creation requires creating a new Codex admin instance for you, it might take some time for the first time until everything is ready. After that your changes will be seen quickly in the playground URL.
Network stability
When running your Codex admin preview on cloud, you need to make sure that you have stable network connection to see all the changes in the Codex Admin for your plugins. Any network related issue in your computer (or any infrastructure issue on Codex) might impact the live preview of your changes in Codex admin, such as latencies or loss of syncronization.