A Koji repository contains everything that defines your development project, including the source code, assets, and configuration data. This topic describes a typical repository structure and defines the configuration data that is required to develop and deploy apps on Koji.
The Koji platform uses Git for source control. When you start a new project by forking a scaffold or another app, the Koji platform creates a clone of the underlying repository. Your new repository is hosted on Koji’s CDN and is associated with the following Git repositories.
origin – Git repository for your new project.
Your app is built and deployed from this repository.
To work locally, you can clone the repository and push changes to it.
upstream – Git repository from which your project was forked.
To propose changes to the app you forked, you can create pull requests for this repository.
If you open your project in the Koji code editor, the development environment includes the project directory at /usr/src/app and Git remotes for these repositories.
To see the remotes, you can open a terminal tab and run git remote -v.
root@c8ce449b5538:/usr/src/app# git remote -v
origin https://projects.koji-cdn.com/8a129043-4c22-4be7-875f-38b422008695.git (fetch)
origin https://projects.koji-cdn.com/8a129043-4c22-4be7-875f-38b422008695.git (push)
upstream https://projects.koji-cdn.com/e4d6b4bf-781a-4a49-9f0f-1d9cf3bbb7ff.git (fetch)
upstream https://projects.koji-cdn.com/e4d6b4bf-781a-4a49-9f0f-1d9cf3bbb7ff.git (push)A typical Koji project contains the koji.json configuration file and a README file at the root of the project directory, along with a directory for each service in the app.
In the following example, the project contains directories for the app’s backend and frontend services.
backend
├── src
├── package-lock.json
├── package.json
frontend
├── src
├── package-lock.json
├── package.json
koji.json
README.mdThe koji.json file defines the instructions for building your code and deploying your app on the Koji platform.
It also defines the settings that are required for certain platform features.
To implement these platform features in your app, initialize the @withkoji/core package with the configuration data in the koji.json file.
The develop key defines the configuration instructions for a development environment, such as the Koji code editor.
For each service in your app, specify the following properties:
path – Source code directory for the service.
port – Port on which the development server will run.
startCommand – Script that initiates a development build.
Define the script in the package.json file of the service directory.
In the following example, the development configuration defines frontend and backend services.
"develop": {
"frontend": {
"path": "frontend",
"port": 8080,
"startCommand": "npm start"
},
"backend": {
"path": "backend",
"port": 3333,
"startCommand": "npm run start-dev"
}
},The deploy key defines the configuration instructions for a production deployment of your app.
For each service in your app, specify the following properties:
output – Directory where the files produced by the build are stored.
type – One of the following: static if the service deploys a static bundle (HTML, CSS, JS) or dynamic if the service deploys a server.
commands – Steps to build your project.
In the following example, the deployment configuration defines a static frontend and a dynamic backend service.
"deploy": {
"frontend": {
"output": "frontend/build",
"type": "static",
"commands": [
"cd frontend",
"npm install",
"export NODE_ENV=production && npm run build"
]
},
"backend": {
"output": "backend",
"type": "dynamic",
"commands": [
"cd backend",
"npm install",
"export NODE_ENV=production && npm run compile"
]
}
},The entitlements key configures the Koji platform features that are implemented in your app.
For a list of available entitlements, go to entitlements.html.
In the following example, the app allows creators to configure it (InstantRemixing), hides the default platform navigation for this configuration (InstantRemixingNativeNavigation), and defines custom sharing data (CustomMetadata).
"entitlements": {
"InstantRemixing": true,
"InstantRemixingNativeNavigation": true,
"CustomMetadata": {
"enabled": true,
"metadata": {
"title": "Default Title",
"description": "{{remixData.title}}"
}
}
}If your app provides configuration options for creators, the remixData key defines the default values for those settings.
To manage remix data in your app, use the Remix class in the @withkoji/core package.
To provide placeholder values when creators first open the settings, use the @@initialTransform key.
In the following example, the app has a default background color and title that creators can change.
"remixData": {
"backgroundColor": "#ffffff",
"title": "My App"
},If your app provides configuration options for creators, the @@initialTransform key defines the placeholder values that override the default values when a creator first opens these settings.
To open the settings in your app, use the .createRemix method in the UI/Navigate class.
If a placeholder value is not specified, the default values in the remixData key are used.
In the following example, the app resets the title to a placeholder value when creators first configure it.
"@@initialTransform": {
"remixData": {
"title": "Name your App"
}
},Optionally, the metadata key can be used to override the following properties.
projectId – String, Unique identifier for the Koji.
creatorUsername – String, Creator’s username.
creatorProfilePicture – String, URL reference to the creator’s current profile picture.
If this key is not specified, the platform provides this metadata at runtime, which enables your app to use the creator’s current username and profile picture without collecting or managing it as remix data.
The README.md file is required at the top level your project directory.
This markdown file should document the tech stack and any relevant information to aid someone working with the code.
This file is particularly important when you are developing a scaffold or another app that other developers can fork to start their projects.