Adonis Log Viewer adds a browser UI to your AdonisJS application so you can open, search, filter, and paginate logs without reading raw files on disk. The layout and flow are inspired by great Laravel tooling such as OPcodes Log Viewer (README), adapted for Node and Adonis.

Features

• Browse log files under your app’s logs/ directory
• Search and sort log lines; paginate results
• Level-style filtering and counts where the viewer supports them
• JSON log lines mapped into table columns when possible
• UI served at /logs · REST API at /api/v1/logs

Official deep documentation for this repo may grow over time; for now this README is the source of truth for install and usage.

Requirements

| Requirement | Supported version | |-------------|-------------------| | AdonisJS | 6.x or 7.x (@adonisjs/core ^6.0 or ^7.0; dev app uses ^7.3) | | Node.js | 20.6 or newer (recommended: current Active LTS, e.g. 22.x) | | npm | 10 or newer (ships with Node 20+); pnpm/yarn are fine if your team standardises on them |

AdonisJS 7 apps typically use Node 24+; AdonisJS 6 apps often run on Node 20+. This package requires Node ≥ 20.6 regardless of framework version. The repository root package.json lists an engines field so npm install can warn when your runtime is too old.

Installation

There are two ways people use Adonis Log Viewer: run the full project from Git (demo / reference app), or wire the viewer into an existing Adonis 6 or 7 application. Pick one.

A. Run this repository as the app

1. Clone:

   git clone https://github.com/<your-org>/adonis-log-viewer.git
   cd adonis-log-viewer

2. Install from the repo root:

   npm install

3. Configure the backend:

   cp app/backend/.env.example app/backend/.env
   cd app/backend
   node ace generate:key
   node ace migration:run
   cd ../..

4. Build this package (UI + compiled provider) and start the demo backend (see Usage).

B. Install into an existing Adonis 6 or 7 app (npm package)

Adonis Log Viewer is an npm package: it bundles compiled server code (dist/), the built SPA (resources/logs_viewer/), and a service provider that registers /logs and /api/v1/logs. You do not copy controllers or routes into your app.

1. Add the dependency (examples):

   npm install adonis-log-viewer

   npm install ../path/to/adonis-log-viewer

   npm link adonis-log-viewer

   For npm link or a path install of this monorepo, run npm install then npm run build inside adonis-log-viewer first so dist/ and resources/logs_viewer/ exist (the linked folder must look like what gets published). In this repository, the demo app pins the package with file:../.. in app/backend/package.json.

2. Register the provider in adonisrc.ts alongside your other providers:

   () => import('adonis-log-viewer/provider'),

3. CORS — If the UI is loaded from another origin, allow it in config/cors.ts (this demo includes CORS_ORIGIN in .env.example).

Restart your server and open {APP_URL}/logs.

Peers: @adonisjs/core ^6.0 or ^7.0 (your app already has this). mime-types is a dependency of adonis-log-viewer; you do not add it separately.

Usage

Production-style (built UI)

From the repository root:

npm run build

This writes the SPA to resources/logs_viewer/ and emits the package entry under dist/.

Then build and run the demo backend:

cd app/backend
node ace build
npm start

Open http://<HOST>:<PORT>/logs (defaults are often localhost and 3333 — see app/backend/.env).

Local development (Vite HMR)

Terminal 1

npm run dev:backend

Terminal 2

npm run dev:frontend

By default in development, /logs uses the same-origin built UI at /logs/assets/* (no separate Vite process). Enable LOGS_VITE_DEV on Adonis when you run Vite with HMR (see Configuration).

Configuration

| Variable | Where | Purpose | |----------|--------|---------| | HOST, PORT | app/backend/.env | URL of your Adonis server | | APP_KEY | app/backend/.env | Required Adonis secret; run node ace generate:key | | LOGS_VITE_DEV | process env (Adonis) | Dev only; set to 1, true, or yes to load /logs scripts from the Vite dev server (LOGS_VITE_ORIGIN) instead of same-origin /logs/assets/* | | LOGS_VITE_ORIGIN | process env (Adonis) | Only when LOGS_VITE_DEV is set; default http://localhost:5173 | | LOGS_VITE_BASE | process env (Adonis) | Only when LOGS_VITE_DEV is set; default /logs/assets (must match Vite base) | | LOGS_USE_BUILT_UI | process env (Adonis) | Dev only; optional explicit 1 / true / yes to force built assets (e.g. overrides a set LOGS_VITE_DEV) | | CORS_ORIGIN | optional in .env | Comma-separated origins if you call the API from another host |

Log files are read from logs/ at the Adonis application root (app.makePath('logs')).

Integrating into your Adonis app

After npm install adonis-log-viewer:

1. Add () => import('adonis-log-viewer/provider') to providers in adonisrc.ts.
2. files published with the package: route registration is handled by VueNiceLogsProvider (start hook → Router).

If you fork and change /logs, update base in app/frontend/vite.config.js, npm run build at repo root (so resources/logs_viewer/ and matching URLs stay aligned), and adjust the prefixes in src/providers/vue_nice_logs_provider.ts before npm publish / linking.

Troubleshooting

Logs not appearing

• Confirm files exist under logs/ at your Adonis app root and the Node process can read them.
• Plaintext and JSON lines are supported in different ways (JSON tries to populate columns).

Blank page at /logs in production

• Ensure node_modules/adonis-log-viewer/resources/logs_viewer/app.js and app.css exist (included in the published tarball).
• npm link / folder install: run npm run build in adonis-log-viewer so those files are generated locally.
• Check the browser network tab for 404s on /logs/assets/....

Dev mode can’t load Vite scripts (CORS / localhost:5173)

Default: in development, /logs already uses same-origin /logs/assets/app.js (built UI). You only see http://localhost:5173/... if LOGS_VITE_DEV=1 (or true / yes) is set on Adonis.

If you unset LOGS_VITE_DEV and still get 5173 errors, restart the Adonis server and ensure you are on a build that includes this behavior. For path installs, run npm run build in adonis-log-viewer so resources/logs_viewer/app.js and app.css exist.

Using Vite + HMR: set LOGS_VITE_DEV=1, start npm run dev:frontend (this repo) or your vite dev server, and set LOGS_VITE_ORIGIN to the origin as the browser reaches it (e.g. Docker: http://host.docker.internal:5173). Expose 5173 through firewalls and port mappings.

Cross-origin <script type="module"> loads can fail if Vite is not running; Firefox may show “CORS request did not succeed” with status: (null) when 5173 is unreachable.

Optional: LOGS_USE_BUILT_UI=1 forces built assets in dev even if LOGS_VITE_DEV is set.

Adonis config/cors.ts does not apply to scripts served by Vite; this package’s app/frontend/vite.config.js sets server.cors for the Vite dev server.

Contributing

Please see CONTRIBUTING.md — structured like OPcodes Log Viewer CONTRIBUTING but for npm, Vue, and Adonis.

Credits

• Inspired by opcodesio/log-viewer (README)

License

The MIT License — see LICENSE.