egg-qeelyn-framework

1.6.0 verified Mon Apr 27 auth: no javascript maintenance

Egg.js-based server-side framework (version 1.6.0) that extends Egg.js with pre-configured JSON logging, Redis integration, common controllers for user authentication (login, logout, SPM), middleware for JWT API auth, request signing, and anti-replay, plus services for HTTP requests, email, and user center. Release cadence: low (last update 2020). Key differentiator: opinionated framework aimed at reducing boilerplate for Egg.js microservices with built-in auth and SPM (Single Page Message) support.

Common errors

error Error: Can't find module 'egg-qeelyn-framework' required by 'egg' ↓

cause Missing or incorrect package.json 'egg.framework' field, or package not installed.

fix

Ensure egg-qeelyn-framework is added to dependencies and package.json has { "egg": { "framework": "egg-qeelyn-framework" } }

error Error: ENOENT: no such file or directory, open '.../config/rsa_pub.pem' ↓

cause Missing RSA public key file needed for JWT verification.

fix

Place a valid RSA public key file at app/config/rsa_pub.pem (or update config.publicKeyPath).

error TypeError: app.middleware.qeelynApiAuth is not a function ↓

cause Middleware accessed without parenthesis — it returns a middleware factory, not a direct middleware.

fix

Use app.middleware.qeelynApiAuth() to get the middleware function.

error Error: connect ECONNREFUSED 127.0.0.1:6379 ↓

cause Redis connection failure when using SPM or cache. Framework assumes Redis is configured.

fix

Either configure Redis properly in config.cache.redis or disable features that require Redis.

Warnings

gotcha Framework requires RSA public key (rsa_pub.pem) in app/config/ for JWT verification. Missing file causes middleware to throw during authentication. ↓

fix Place a valid RSA public key file at app/config/rsa_pub.pem.

breaking Framework depends on egg ^2.x. Incompatible with egg 3.x. ↓

fix Use egg ^2.0.0; do not upgrade to egg 3.x without migration.

deprecated Extend/context.js: ctx.logger for JSON logging is marked as deprecated (currently abandoned). ↓

fix Use ctx.logger.info() or structured logging from egg directly.

gotcha Middleware must be called as a function (e.g., app.middleware.qeelynApiAuth()) to instantiate; passing the function directly as middleware will fail. ↓

fix Always call .qeelynApiAuth() with parentheses when using in route.

breaking SPM (Single Page Message) functionality requires Redis. If Redis is not configured, SPM endpoints will throw connection errors. ↓

fix Configure Redis in config.default.js under config.cache.redis.

Install

npm install egg-qeelyn-framework

yarn add egg-qeelyn-framework

pnpm add egg-qeelyn-framework

Imports

default

wrong

expecting npm require('egg-qeelyn-framework') as module

correct

in package.json: { "egg": { "framework": "egg-qeelyn-framework" } }

Not imported directly; used as Egg.js framework via package.json egg.framework field.

ctx.helper.jsonResult
wrong
```
ctx.helper.json(data, error)
```
correct
```
ctx.helper.jsonResult(data, error)
```
Available after proper framework setup; defined in extend/helper.js.
app.middleware.qeelynApiAuth
wrong
```
app.middleware.qeelynApiAuth
```
correct
```
app.middleware.qeelynApiAuth()
```
Must call as function to get middleware.

Quickstart

Shows how to set up framework, configure, define routes, and use built-in controllers and middleware.

// package.json
{
  "name": "my-app",
  "egg": {
    "framework": "egg-qeelyn-framework"
  },
  "dependencies": {
    "egg": "^2.0.0",
    "egg-qeelyn-framework": "^1.6.0"
  }
}

// config/config.default.js
'use strict';
module.exports = appInfo => {
  const config = {};
  config.keys = appInfo.name + '_v1.0.0';
  config.appCode = 'myAppCode';
  // required for JWT auth: public key
  config.publicKeyPath = require('path').join(appInfo.baseDir, 'config/rsa_pub.pem');
  config.api = {
    deoGateway: 'https://gateway.example.com',
    ucenterAuth: 'https://ucenter.example.com',
  };
  config.pageConfig = {
    loginUrl: 'https://login.example.com',
    ucenterHost: 'https://ucenter.example.com',
  };
  config.cache = {
    redis: {
      port: 6379,
      host: '127.0.0.1',
      db: 0,
    },
  };
  return config;
};

// app/router.js
'use strict';
module.exports = app => {
  const { router, controller } = app;
  // Use built-in controllers
  router.post('/qeelyn-framework/usercenter-api', controller.qeelynFrameworkApi.ucenterApi);
  router.get('/qeelyn-framework/logout', controller.qeelynFrameworkApi.logout);
  router.get('/qeelyn-framework/log', controller.qeelynFrameworkApi.log);
  router.post('/qeelyn-framework/spm', controller.qeelynFrameworkApi.spm);
  
  // Use middleware for API routes
  const qeelynApiAuth = app.middleware.qeelynApiAuth();
  const qeelynValidSign = app.middleware.qeelynValidSign();
  const qeelynLog = app.middleware.qeelynLog();
  router.post('/api/protected', qeelynValidSign, qeelynLog, qeelynApiAuth, controller.api.index);
};