Getting Started

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.

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

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.

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

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

Publishing the code

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, 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

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 [email protected]:MyUsername/MyRepository.git
git push -u origin main

Developer 2

git clone [email protected]:MyUsername/MyRepository.git
cd MyRepository/
npm install
cp .env.example .env

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