easy integration into node projects

[wiktor-jurek]

Hey team - love this initiative! I'm developing stratuscribe.com and this has been an awesome resource. Are you against me 'wrapping' this project into an npm package? Could I do that for easy updating?

[anhthang]

Wrapping this into an npm package is a great idea. The project's still in active development, so I haven't fully planned the packaging and update flow yet. If you're up for it, I'd love a pull request with the initial package setup (build config, entry points, versioning, and publish steps). I can review it and publish the package soon after.

Appreciate the help!

[anhthang]

@wiktor-jurek I have published an alpha on npm: https://www.npmjs.com/package/soaring-symbols

Please let me know if you have any feedback on the API, catalog, or asset paths.

I'm still refining how to handle mono vs. color for airlines that use a single‑color model. There may be adjustments as this settles, but I'll aim to keep changes minimal and clearly documented.

[wiktor-jurek]

I haven't been able to test this out - but I'll try get to it in the next week or so. This is super helpful if it works 🤞

[anhthang]

I saw hundreds of downloads on npm, so it looks like folks have tested it. If you run into any issues, let me know and I’ll take a look.

[wiktor-jurek]

I tried to use soaring-symbols in a Next.js 16 API route, the package cannot be imported due to a module export configuration issue. The package uses CommonJS internally (module.exports) but the package.json only declares ESM exports, causing import failures.

• Package Version: soaring-symbols@0.1.0-alpha.4
• Framework: Next.js 16.0.1 with Turbopack
• Node.js: v23.3.0
• Import Type: ESM (in Next.js API Route)

Steps to Reproduce

1. Install soaring-symbols in a Next.js project
2. Create an API route that imports from the package:

// app/api/airline-icon/route.ts
import { getAssets } from 'soaring-symbols';

export async function GET(request: NextRequest) {
  const assets = getAssets('FR'); // Ryanair
  // ... use assets
}

3. Try to build or run the dev server

Expected Behavior

The import should work seamlessly, allowing use of listAirlines(), getAirline(), and getAssets() functions as documented in the README.

Actual Behavior

Error 1: CommonJS require() in ESM context

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in /path/to/node_modules/soaring-symbols/package.json

Error 2: During Next.js build

Module not found: Can't resolve 'fs'

Import traces:
  ./node_modules/soaring-symbols/utils/index.js
  ./node_modules/soaring-symbols/index.js

The build fails because utils/index.js uses Node.js fs module which cannot be bundled for client-side code.

Root Cause Analysis

1. Mixed Module System: The package uses CommonJS (module.exports) in index.js but the package.json only declares ESM exports:

{
  "main": "index.js",
  "module": "index.js",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.js"  // ❌ Only ESM, no "require" field
    },
    "./assets/*": "./assets/*"
  }
}

2. Node.js Built-ins: The utils/index.js file uses fs, path, which causes bundler issues in edge/client environments.

Current Workaround

We had to bypass the package's API and directly read the files:

import { readFileSync } from 'fs';
import { join } from 'path';

// Read airlines.json directly instead of using getAssets()
const airlinesJsonPath = join(process.cwd(), 'node_modules', 'soaring-symbols', 'airlines.json');
const airlinesData = JSON.parse(readFileSync(airlinesJsonPath, 'utf-8'));

// Find airline manually
const airline = airlinesData.find(a => 
  a.iata?.toUpperCase() === code || 
  a.icao?.toUpperCase() === code
);

// Construct asset path manually
const assetPath = join(
  process.cwd(),
  'node_modules',
  'soaring-symbols',
  'assets',
  airline.slug,
  'icon.svg'
);

const svgContent = readFileSync(assetPath, 'utf-8');

Use Case

We're building a flight tracking app (StratusScribe) and want to display airline logos dynamically based on airline codes. The package's asset organization and data structure are perfect for our needs, but the module system issues prevent us from using it as intended.

Thank you for maintaining this valuable resource! 🛫

[anhthang]

@wiktor-jurek Thanks for the detailed report — really helpful. I’m working through the issues now. I’ve also published a new build to better handle ESM/CJS so the API should work across environments. I’m considering changing ‎⁠getAssets⁠ to return the SVG content directly, which should avoid the ‎⁠fs⁠/bundling problems.

If you have thoughts on that return shape, I’d love your input.

[wiktor-jurek]

Honestly I thought that's what the getAssets function would have done (rtfm :)). I think that would be more intuitive and would help abstract away the getAssets, then having to get the SVGs ourselves.