Skip to main content

Directory Structure

Building a scalable application with geajs requires a clear and intentional directory structure. Since geajs relies heavily on standard JavaScript/TypeScript classes, separating responsibilities early prevents memory management issues and messy component references.

Minimal Structure (Default)​

When you first generate a project, the directory structure might look like this:

my-app
├── index.html
├── package.json
├── public
│  ├── favicon.ico
│  └── logo.png
├── src
│  ├── app.tsx
│  ├── counter-note.tsx
│  ├── counter-panel.tsx
│  ├── counter-store.ts
│  ├── globals.d.ts
│  ├── main.ts
│  └── styles.css
├── tsconfig.json
└── vite.config.ts

This works well for tiny experiments or single-page prototypes. However, as your class hierarchy grows, putting all logic directly under src/ can lead to tight coupling.

For medium to large applications, we recommend organizing your src/ directory by responsibility:

src/
├── components/     # Reusable UI components (classes)
│   ├── common/     # Buttons, Modals, Inputs
│   │               # ^ However, since these are already provided by `@geajs/ui`,
|   |               # | this is essentially where we place the components that aren't included in that package.
│   └── layout/     # Header, Sidebar, Footer
├── views/          # Page-level components or main feature containers
│   ├── home/
│   └── dashboard/
├── services/       # Business logic, API calls, state managers
├── utils/          # Pure helper functions
├── styles/         # Global CSS or theme definitions
├── main.ts         # Application entry point
└── globals.d.ts    # Global TypeScript declarations

Key Takeaways​

  • Separate UI and Logic: Keep API fetching or state handling inside services/ rather than embedding it inside UI component classes.
  • Explicit Lifecycle Scope: Grouping components by feature or domain makes it easier to track which classes need to be disposed of when navigating between views.
Compatibility Issues Between Vite and @geajs/vite-plugin

When building an application with GeaJS, you may encounter an error stating [gea-plugin] Could not resolve @geajs/core compiler runtime upon starting Vite and accessing the page. This occurs because the plugin's code does not currently support Vite's dependency pre-bundling feature. (This behavior applies to @geajs/vite-plugin as of version 1.4.1. It may be resolved in later versions.) For a detailed solution and workarounds, please check the GitHub Issue.