{"id":12845,"library":"atma-server","title":"Atma.js Server Module","description":"Atma.js Server is a Node.js server module providing a framework for building HTTP applications, leveraging other components within the Atma.js ecosystem like `atma-logger`, `atma-io`, and `appcfg`. It allows for flexible routing, middleware processing (compatible with Connect.js middleware), and resource management for both server-side and client-side assets. The module is currently at version 0.5.30, indicating a pre-1.0 development stage, and is likely in a maintenance or active development phase within its specific ecosystem, rather than a general-purpose, high-cadence release cycle. Key differentiators include its tight integration with Atma.js libraries for configuration, logging, and I/O, and its structured approach to defining application, service, handler, and page endpoints with custom pipelines.","status":"maintenance","version":"0.5.30","language":"javascript","source_language":"en","source_url":"https://github.com/atmajs/atma-server","tags":["javascript","typescript"],"install":[{"cmd":"npm install atma-server","lang":"bash","label":"npm"},{"cmd":"yarn add atma-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add atma-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for logging within the Atma.js ecosystem.","package":"atma-logger","optional":false},{"reason":"Used for file system operations and resource handling.","package":"atma-io","optional":false},{"reason":"Used for loading and managing application configurations.","package":"appcfg","optional":false},{"reason":"Can be used as a Connect middleware; compatible with Connect-style middleware functions.","package":"connect","optional":true},{"reason":"Commonly integrated as middleware for handling request bodies.","package":"body-parser","optional":true}],"imports":[{"note":"The `Application` factory is nested under the `server` property of the main export. For CommonJS, `const atma = require('atma-server'); const app = atma.server.Application(...);` is correct.","wrong":"import AtmaServer from 'atma-server';\nconst app = AtmaServer.Application(...);","symbol":"Application","correct":"import { server } from 'atma-server';\nconst app = server.Application(...);"},{"note":"Static file middleware is exported under the `middleware` property of the `server` object. The `static` keyword cannot be directly imported as a named export without aliasing.","wrong":"import { static } from 'atma-server/middleware';\n","symbol":"middleware.static","correct":"import { server } from 'atma-server';\nconst staticMiddleware = server.middleware.static;"},{"note":"Type import for configuring the server application. The library ships with TypeScript types.","symbol":"HttpApplicationOptions","correct":"import type { HttpApplicationOptions } from 'atma-server';"}],"quickstart":{"code":"import { server } from 'atma-server';\nimport bodyParser from 'body-parser';\nimport path from 'path';\n\nconst __dirname = path.resolve();\n\nserver\n    .Application({\n        base: __dirname,\n        configs: '/server/config/**.yml' // Configure path to YAML configs\n    })\n    .done(function(app){\n        console.log('Atma server application loaded and configured.');\n\n        app.processor({\n                before: [\n                    (req, res, next) => { console.log('Before pipeline:', req.url); next(); },\n                ],\n                middleware: [\n                    (req, res, next) => { console.log('Middleware pipeline:', req.url); next(); },\n                    bodyParser.json(), // Common middleware for JSON body parsing\n                ],\n                after: [\n                    (req, res, next) => { console.log('After pipeline:', req.url); next(); },\n                    server.middleware.static // Serve static files as a fallback\n                ]\n            })\n            .listen(); // Start the server on the configured port\n\n        console.log(`Server attempting to listen on port from config or default.`);\n        // Example manual server start (optional, listen() is preferred):\n        // const httpServer = require('http')\n        //     .createServer(app.process)\n        //     .listen(app.config.$get('port') || 3000);\n        // if (app.config.debug)\n        //     app.autoreload(httpServer);\n    });","lang":"typescript","description":"This quickstart initializes an Atma.js server application, configures its base path and configuration file location, and sets up request processing pipelines with `before`, `middleware`, and `after` stages. It includes `body-parser` as a common middleware and the built-in static file handler, then starts the server to listen for incoming requests based on its configuration."},"warnings":[{"fix":"Ensure a build step is in place for production deployments that executes `atma custom node_modules/atma-server/tools/compile` to bundle client-side resources.","message":"Resource compilation for production environments differs significantly from development. In development, client-side scripts/styles are served individually; for production, they must be manually compiled using `atma custom node_modules/atma-server/tools/compile`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use `import { server } from 'atma-server';` for ESM. For projects strictly enforcing ESM, ensure your `tsconfig.json` and `package.json` (`\"type\": \"module\"`) are correctly configured to handle hybrid modules.","message":"The `atma-server` library examples and internal structure primarily demonstrate CommonJS usage (`require`). While it ships with TypeScript types, users targeting pure ESM environments may need to adapt import statements and potentially configure their build process for compatibility.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Verify that your `configs` path in `server.Application` correctly points to your YAML configuration files and that the files themselves are syntactically valid and contain expected keys like `port` and resource definitions.","message":"Configuration files are loaded via `appcfg` from the `/server/config/**.yml` path by default. Misconfigurations or incorrect paths in `configs` property of `Application` can lead to the server failing to start or behave as expected.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Prefer `app.listen()` for starting the server to ensure all integrated features, including automatic port discovery from configuration and debug autoreload, function correctly.","message":"The primary method to start the HTTP server is `app.listen()`. While it's possible to manually create an HTTP server with `require('http').createServer(app.process).listen(...)`, this bypasses some internal features like `app.autoreload` (for debug mode) and relies on manually retrieving the port from configuration.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the `port` setting in your `app.yml` or relevant configuration file, or ensure no other application is using the intended port. You can find and terminate the process using `lsof -i :PORT` (macOS/Linux) or `netstat -ano | findstr :PORT` (Windows).","cause":"The configured port for the Atma server is already in use by another process on the system.","error":"Error: listen EADDRINUSE: address already in use :::3000"},{"fix":"Ensure the `Application` factory completes successfully before calling `app.processor()`. This typically means waiting for the `.done()` callback to execute. Check for any errors during the `Application` initialization, potentially in your configuration files.","cause":"The `Application` instance (`app`) did not correctly initialize or was not returned as expected, leading to a missing `processor` method.","error":"TypeError: app.processor is not a function"},{"fix":"Double-check the `base` and `configs` paths provided to `server.Application`. Ensure they are correct and that the YAML files exist at the specified locations relative to the base path. Use absolute paths for `base` if unsure about relative resolution.","cause":"The `atma-server` application cannot find one or more of the configuration files specified in the `configs` option during initialization.","error":"Error: ENOENT: no such file or directory, stat '/path/to/server/config/default.yml'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}