Getting Started

This is the official documentation of Forest Admin Cloud.

Forest Admin gives you access to the underlying code of your admin panel to fully customize its features. You can then add new actions, fields, collections, charts, and more to personalize your back office capabilities.

This is how Forest Admin guarantees to provide you with the highest level of flexibility, ensuring that you never encounter limitations when implementing your specific requirements.

Due to the nature of the subject, this section is intended for developers.

Getting the code

To access the code of your admin panel locally, click on the <> icon in the bottom left navigation bar and follow the in-app guide:

Once opened, you will be asked to type the following commands in your terminal:

npx @forestadmin/forest-cloud@latest bootstrap --env-secret <your-env-secret> <name>

Replace with name of the folder that will be created locally, typically matching your Forest Admin project.

Replace <your-env-secret> with your environment secret, which is dynamically injected in the in-app guide. You can also find it by accessing the Environments tab in your project settings.

cd <name>/
npm install -s

Explanation of command lines

1. Installs the forest-cloud package and retrieves your admin panel's code.

2. Changes the directory to the one that has the code. Remember to replace <name> with the specific name you used previously.

3. Installs the necessary dependencies.

After these steps, you can open this directory in your favorite IDE to start implementing the code customization. The project consists of a simple NodeJS application developed in TypeScript. All your custom code should be placed within the src/index.ts file.

.
├── LICENSE.md
├── README.md
├── esbuild.mjs
├── nodemon.json
├── package.json
├── src
│   └── index.ts
├── tsconfig.json
└── typings.d.ts

In the src/index.ts file, the customizeAgent function accepts an agent instance as its parameter. By invoking the agent's customizeCollection method within this function, you can tailor a specific collection by adding new actions, fields, and other improvements.

src/index.ts

import type { Agent } from '@forestadmin/forest-cloud';
import { Schema } from '../typings';

export default function customizeAgent(agent: Agent<Schema>) {
  // agent.customizeCollection(...
}

Publishing the code

Important information

Always ensure to implement a version control system for keeping track of code customizations. Without such a system, reverting changes to the original version won't be possible.

Finally, once you are ready, publish your changes by running the command:

npm run forestadmin:build:package:publish

Accessing the logs

To view the logs of your currently running code, execute you can use the logs command.

npx forest-cloud logs

By default, this command will retrieve the most recent 30 logs collected within the last month. For additional options, such as adjusting the number of logs displayed or changing the time range, please refer to the command's help page by using:

npx forest-cloud logs --help

Please note that there may be a slight delay of a few seconds in accessing the latest logs.

Developing locally

Rather than pushing your code directly to the production environment to see your changes, it is a best practice to setup a dev environment to test your code locally. This significantly improve the overall developer experience.

To do so, change the database connection string in the datasources.js file to your local database and run npm run dev:watch to start coding in your local environment:

module.exports = () => ({
    main: {
        connectionOptions: {
            uri: "postgres://username:password@localhost:5432/postgres",
        },
    },
})

npm run dev:watch

Finally, refresh your browser and click on the top-left Forest Admin logo to see your new development environment.

Collaborating with others

As explained in the warning above, we strongly advise setting up a Source Control Management (SCM) system such as Git, as the original code will no longer be accessible once it is published.

Using an SCM tool is also highly recommended for starting collaboration with others, as they would only need to clone your repository, implement some new customizations, and publish the code to Forest Admin. As an example, using Git and GitHub, the development workflow would be something like:

Developer 1

npx @forestadmin/forest-cloud@latest bootstrap <name> --env-secret <your-env-secret>
cd <name>/
git init
git add -A
git commit -am "Initializing my Forest Admin code customization project"
git branch -M main
git remote add origin [e-mail]:MyUsername/MyRepository.git
git push -u origin main

Explanation of command lines

1. Installs the forest-cloud package and retrieves your admin panel's code. Replace <name> with your project's folder name and <your-env-secret> with your Environment secret found under the Environments tab in your Project settings.

2. Changes the directory to where your code is located, replacing <name> with your specific directory name.

3. Initializes a new Git repository.

4. Adds all changes in the working directory to the staging area.

5. Commits all the changes.

6. Renames the branch to main.

7. Adds a new remote pointing to a Github repository. Don't forget to replace MyUsername and MyRepository with the appropriate values.

8. Pushes code to GitHub.

Developer 2

git clone [e-mail]:MyUsername/MyRepository.git
cd MyRepository/
npm install
cp .env.example .env

Explanation of command lines

1. Clones the existing Github repository. Don't forget to replace MyUsername and MyRepository with the appropriate values.

2. Changes the directory to your code's location. Replace MyRepository with your GitHub repository name.

3. Installs all the necessary dependencies.

4. Copies the .env.example file to the .env file.

In the .env file, replace the FOREST_ENV_SECRET environment variable with your environment secret. You can find your environment secret by navigating to the Environments tab in your Project settings and selecting the environment you want to customize.

Finally, Developer 2 can implement the new customization code into the project. Once ready, they can commit and push their changes to the GitHub repository and publish their updates on Forest Admin.

git add -A
git commit -am "Adding <some Forest Admin customization>"
git push
npm run forestadmin:build:package:publish

Explanation of command lines

1. Adds all changes in the working directory to the staging area.

2. Commits all the changes.

3. Pushes code to GitHub.

4. Publishes the code to Forest Admin.