Entity App Server Project Scaffolder

0.8.1 · active · verified Sun Apr 19

The `create-entity-app-server` package, currently at version 0.8.1, serves as a command-line tool for scaffolding new application server projects based on Fastify and integrated with Entity Server. It provides an opinionated project structure designed for rapid development and clear separation of concerns. The core server functionalities, including authentication, CRUD operations for entities, and file storage, are encapsulated within a pre-compiled `system.js` bundle, keeping the server's foundational logic abstracted. Developers are primarily expected to implement business logic, custom API routes, entity event hooks, and background schedules within the `app/` directory, written in TypeScript. This package distributes a template that sets up necessary files, configurations, and scripts, allowing developers to immediately run a development server. While the package itself is a scaffolder, the generated project features an active development cadence typical of `0.x` versions. Its key differentiators include a 'hidden' core for reduced boilerplate, a strong focus on customizability via TypeScript, and predefined alias rules (`@system/api`, `@app/*`) to guide module imports within the generated codebase.

Common errors

```
Error: The Entity App Server requires Node.js v18 or greater. You are currently running vXX.
```
cause The `npm run dev` command (or any script running the generated project) was executed using an unsupported Node.js version.

fix Update your Node.js environment to version 18 or higher. If you have multiple Node.js versions installed, ensure the correct version is active in your terminal session (e.g., `nvm use 18`).
```
Error: Cannot find module 'system.js' from '<project_root>/src/index.ts'
```
cause This error typically occurs if the development server command (`npm run dev`) is not executed from the root directory of your newly created project, or if the initial setup failed to generate the `system.js` file.

fix Ensure you have navigated into your project directory (e.g., `cd my-app`) after running `npm create entity-app-server`. Then, run `npm install` followed by `npm run dev`. Verify that `system.js` exists in your project's root folder.

Warnings

gotcha The `configs/config.example.json` file serves as a template for configuration and should be managed separately from the deployed `configs/config.json`. `config.example.json` should generally omit build control fields like `deploy` or `minify`, which are specific to the production `config.json`. Mismanaging these files can lead to unexpected build or deployment behavior.
Fix: Ensure `config.json` is correctly derived from `config.example.json` and that build-specific fields are applied only in the deployment configuration, or removed during a build process if they originate from source `config.json`.
breaking The generated Entity App Server project explicitly requires Node.js version 18 or higher as indicated by the `engines` field in `package.json`. Attempting to run the project with older Node.js versions will result in compatibility issues or a complete failure to launch.
Fix: Upgrade your Node.js environment to version 18 or newer. Tools like `nvm` (Node Version Manager) are highly recommended for managing multiple Node.js versions efficiently.
gotcha Within the generated `app/` source code, it is crucial to adhere to the documented path alias rules. Always import system functionalities intended for public use via the `@system/api` alias. Directly importing modules from `@system/*` aliases (which expose internal system core modules) is discouraged, as these are subject to internal changes and can lead to breakage with future updates.
Fix: For consuming system features in `app/` code, use `import { somePublicApi } from '@system/api'`. Avoid `import { internalModule } from '@system/some-internal-path'` to maintain stability and compatibility.

Install

npm install create-entity-app-server npm
yarn add create-entity-app-server yarn
pnpm add create-entity-app-server pnpm

Quickstart

Initializes a new Entity App Server project, installs dependencies, and starts the development server.

npm create entity-app-server@latest my-app
cd my-app
npm install
npm run dev

view raw JSON →