Getting Started

This guide describes how to get started with SynergiWeb app development. While it is possible to develop applications with the standard Appframe Web framework, there are some advantages to using the method used in most of our apps:

• Better linting and error checking with Typescript

• Unlock the full power of VS Code and extensions

• Easier to use 3rd party NPM packages

• Better version control with Git

It is recommended to have basic knowledge of Typescript and React before starting with SynergiWeb development.

Development Environment

If on Windows, using WSL2 is recommended, but not required. Node.js (20+) and Git are required. You can use your preferred code editor. If you don't have a code editor, VSCode is a good option.

Since we have a lot of repositories with similar dependencies, we use pnpm instead of npm, since this means we don't need to have a node_modules folder of hundreds of MB for each project. Install with npm:

npm install -g pnpm
pnpm setup

This repository exposes common tasks as pnpm scripts, so a global CLI is not required. Key scripts:

• pnpm init-app: scaffold a new app from the template/ folder.

• pnpm --filter <app> start: run an app’s Vite dev server.

• pnpm generate-types: regenerate Appframe TypeScript definitions for an app.

• pnpm copy-datasources: copy data objects between environments when needed.

• pnpm update-setup: align an app with the latest template patches.

Optional: You can still install the global Appframe CLI (pnpm i -g @olenbetong/appframe-cli) if you prefer, but the scripts above cover day‑to‑day development in this repo.

Our application template uses Vite, but it is not necessary with any knowledge of how it works. Our Vite plugin (@olenbetong/appframe-vite) and the provided scripts handle everything needed for basic applications.

The development server uses a proxy to enable you to request data directly from Appframe. For the proxy to work, you'll need to supply a username and password using environment variables. Username should be in APPFRAME_LOGIN, and password in APPFRAME_PWD. These environment variables are also used by the CLI, but unlike the CLI, the proxy will not prompt for username and password if they are not present.

Development Process

For information on how to initialize a new project, see Creating a new application.

For existing applications, simply clone the repository with git:

git clone https://github.com/olenbetong/namespace-app-name.git

Then, from the repository root, run pnpm install to install all dependencies.

You can check if dependencies are up to date by running pnpm outdated. Alternatively you can use npm-check to run an interactive guide (when available via a local check script).

pnpm run check

To develop, either:

cd apps/<app>
pnpm start

or from the repo root use workspaces:

pnpm --filter <app> start

If you run into problems starting or building an app, run pnpm update-setup to align it with the latest template patches. This helps migrate away from legacy package versions, adds missing config files, and updates Appframe settings in package.json as needed.

When you are ready to publish your application, you can use the CLI or Github actions to deploy it. See Deploying to production for more information.