FIS3 Node.js Server

Common errors

• Error: Cannot find module 'fis3-server-node'

  cause The package is not installed as a dependency of `fis3`, or the Node.js environment cannot resolve the module path due to environmental issues or an outdated Node.js version conflicting with global installations.
  fix Ensure `fis3` is installed globally (`npm install -g fis3`), which should bring in its necessary dependencies including this server module. If using a modern Node.js version, consider downgrading to an older, compatible Node.js version (e.g., Node.js 8 or 10) or, preferably, migrating away from this deprecated toolchain.

• ERR_REQUIRE_ESM is not defined in ES module scope

  cause Attempted to import `fis3-server-node` using ES module syntax (`import fis3ServerApp from 'fis3-server-node';`) within an ES module context.
  fix This package is a CommonJS module. Use `const fis3ServerApp = require('fis3-server-node');` for any programmatic interactions. For standard `fis3` CLI usage, no direct import is typically needed within your project code.

• TypeError: Cannot read properties of undefined (reading 'project')

  cause Attempted to run `fis3-server-node` directly or within a Node.js environment where the global `fis` object (expected to be provided by the `fis3` CLI) is not defined, which the server relies on for configuration (e.g., project root).
  fix Always start the server through the `fis3` command-line tool as intended: `fis3 server start --type node`. This ensures the necessary `fis3` execution context and global objects are present.

Warnings

• breaking This package is effectively abandoned. It has not received updates in approximately five years, and the entire `fis3` ecosystem it belongs to is also unmaintained. This means it is highly likely to be incompatible with modern Node.js versions (e.g., Node.js 16+ or later).
  Fix: Migrate your projects to modern build tools and local development server solutions (e.g., Vite, Webpack Dev Server, Parcel) which are actively maintained and support current Node.js and JavaScript standards.
• security Due to its abandoned status, `fis3-server-node` and its underlying `express` dependency (which will also be an old version) are highly likely to contain unpatched security vulnerabilities. Using this package in any environment, especially for public-facing development or CI/CD, poses significant security risks.
  Fix: Discontinue use immediately. There are no security fixes available for this package or its outdated dependencies. Migrate to actively maintained tools and libraries.
• gotcha This package is a CommonJS module and explicitly does not support ES Modules (`import`/`export`). Attempting to import it using ES module syntax will result in a runtime error.
  Fix: If programmatic use is attempted (which is uncommon as its primary use is CLI-driven), always use `const fis3ServerApp = require('fis3-server-node');` syntax. For new projects, prefer modern ES module-compatible tools.
• gotcha The package internally relies on the global `fis` object (e.g., `fis.project.get=root()`), meaning it's tightly coupled to the `fis3` CLI's execution environment. Running it programmatically outside the `fis3` context without manually defining or mocking `fis` will likely cause runtime errors.
  Fix: Always start the server via the `fis3` command-line tool: `fis3 server start --type node`. This ensures the proper `fis3` execution environment is set up and `fis` globals are available.

Install

• npm install fis3-server-node npm
• yarn add fis3-server-node yarn
• pnpm add fis3-server-node pnpm

Imports

• fis3ServerApp
  wrong:

  import fis3ServerApp from 'fis3-server-node';

  correct:

  const fis3ServerApp = require('fis3-server-node');

  This package exports an Express.js application instance directly, which is primarily intended to be used internally by the `fis3` build system's execution context. It is a CommonJS module and does not support ES modules. Direct programmatic use outside the `fis3` CLI is uncommon and requires mocking global `fis` objects.

Quickstart

Demonstrates how to initialize a basic FIS3 project and start its default Node.js server to serve static content via the `fis3` command-line interface.

```bash
# 1. Install fis3 globally (if not already installed)
npm install -g fis3

# 2. Create a new project directory and initialize fis3
mkdir my-fis-project
cd my-fis-project
fis3 init --force # Use --force if the directory is not empty

# 3. Create a simple HTML file for the project root
echo '<!DOCTYPE html><html><head><title>FIS3 Project</title></head><body><h1>Hello from FIS3 Server!</h1></body></html>' > index.html

# 4. Create a fis-conf.js file with minimal configuration
echo "// fis-conf.js\nfis.match('*.html', { release: '/$0' });" > fis-conf.js

# 5. Start the fis3 server using the 'node' type (which implicitly uses fis3-server-node)
fis3 server start --type node

# The server will typically start on http://127.0.0.1:8080 (or another available port).
# Open your browser to the indicated URL to view the 'index.html'.
# Press Ctrl+C in the terminal to stop the server.
```