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.
- 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:
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
.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
An array of objects that represents all the widgets that this plugin is adding in Codex.
routes
An array of objects that represents all the routes and pages that this plugin is adding in Codex.
navigaton
An array of objects that represents all the navigation menu items that this plugin is adding in Codex.
permissions
An array of objects that represents all the permissionns 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.
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
.
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.
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.
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.