{"id":21192155,"url":"https://github.com/mu-semtech/mu-javascript-template","last_synced_at":"2025-07-10T03:31:25.147Z","repository":{"id":8342122,"uuid":"57892583","full_name":"mu-semtech/mu-javascript-template","owner":"mu-semtech","description":"Template for running javascript/express microservices","archived":false,"fork":false,"pushed_at":"2025-05-02T11:41:24.000Z","size":189,"stargazers_count":4,"open_issues_count":14,"forks_count":18,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-02T12:39:55.836Z","etag":null,"topics":["express","javascript","mu-template","musemtech"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mu-semtech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-05-02T13:33:05.000Z","updated_at":"2025-04-14T13:05:46.000Z","dependencies_parsed_at":"2024-05-10T12:24:51.624Z","dependency_job_id":"fa4adf55-9dec-4d7f-9ebc-224a7bb89879","html_url":"https://github.com/mu-semtech/mu-javascript-template","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/mu-semtech/mu-javascript-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mu-semtech%2Fmu-javascript-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mu-semtech%2Fmu-javascript-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mu-semtech%2Fmu-javascript-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mu-semtech%2Fmu-javascript-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mu-semtech","download_url":"https://codeload.github.com/mu-semtech/mu-javascript-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mu-semtech%2Fmu-javascript-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264521149,"owners_count":23622090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","javascript","mu-template","musemtech"],"created_at":"2024-11-20T19:07:44.723Z","updated_at":"2025-07-10T03:31:20.138Z","avatar_url":"https://github.com/mu-semtech.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mu Javascript template\n\nTemplate for writing semantic.works services in JavaScript using [Express 4](https://expressjs.com/)\n\n## Tutorials\n### Develop your first microservice\nRequires: a semantic.works stack, like mu-project.\n\nCreate a new folder for your microservice.\n\nIn the folder, create your microservice in `app.js`:\n\n```js\nimport { app } from 'mu';\n\napp.get('/hello', function( req, res ) {\n  res.send('Hello mu-javascript-template');\n} );\n```\n\nThis service will respond with 'Hello mu-javascript-template' when receiving a GET request on '/hello'.\n\nAdd the mu-javascript-template to your `docker-compose.yml` with the sources mounted directly.\n\n```yml\nversion: '3.4'\nservices:\n    your-microservice-name:\n      image: semtech/mu-javascript-template\n      environment:\n        NODE_ENV: \"development\"\n      ports:\n        - 8888:80\n      volumes:\n        - /absolute/path/to/your/sources/:/app/\n```\n\nNext, create the service by running\n```\ndocker-compose up -d your-microservice-name\n```\n\nA `curl` call to the microservice will show you to message\n\n```bash\ncurl http://localhost:8888/hello\n# Hello mu-javascript-template\n```\n\n## How-to\n### Develop in a mu.semte.ch stack\nRequires:\n- a semantic.works stack, like mu-project\n- 'Develop your first microservice'\n\nWhen developing inside an existing mu.semte.ch stack, it is easiest to set the development mode by setting the `NODE_ENV` environment variable to `development` and mount the sources directly.  This makes it easy to setup links to the database and the dispatcher. Livereload is enabled automatically when running in development mode.\n\n```yml\nversion: ...\nservices:\n  ...\n  your-microservice-name:\n    image: semtech/mu-javascript-template\n    environment:\n      NODE_ENV: \"development\"\n    volumes:\n      - /absolute/path/to/your/sources/:/app/\n```\n\n### Build a microservice based on mu-javascript-template\nRequires:\n- a semantic.works stack, like mu-project\n- 'Develop your first microservice'\n\nAdd a Dockerfile with the following contents:\n\n```docker\nFROM semtech/mu-javascript-template\nLABEL maintainer=\"madnificent@gmail.com\"\n```\n\nThere are various ways to build a Docker image. For a production service we advise to setup automatic builds, but here we will build it locally. You can choose any name, but we will call ours 'say-hello-service'.\n\nFrom the root of your microservice folder execute the following command:\n```bash\ndocker build -t say-hello-service .\n```\n\nAdd the newly built service to your application stack in `docker-compose.yml`\n```yml\nversion: ...\nservices:\n  ...\n  say-hello:\n    image: say-hello-service\n```\n\nLaunch the new container in your app\n```bash\ndocker-compose up -d say-hello\n```\n\n### Attach the Chrome debugger\nRequires: 'Develop in a mu.semte.ch stack'.\n\nWhen running in development mode, you can attach the Chrome debugger to your microservice and add breakpoints as you're used to.  The chrome debugger requires port 9229 to be forwarded, and your service to run in development mode.  After launching your service, open Google Chrome or Chromium, and visit [chrome://inspect/](chrome://inspect/). Once the service is launched, a remote target on localhost should pop up.\n\nUpdate your service definition in `docker-compose.yml` as follows:\n\n```yml\nversion: ...\nservices:\n  your-microservice-name:\n    ...\n    ports:\n      - 9229:9229\n```\n\nNext, recreate the container by executing\n```bash\ndocker-compose up -d your-microservice-name\n```\n\n### Access your microservice directly\nRequires: 'Build a microservice based on mu-javascript-template' or 'Develop in a mu.semte.ch stack'\n\nIf you doubt your requests are arriving at your microservice correctly, you can publish it port to access it directly. In the example below, port 8888 is used to access the service directly.\n\nNote this means you will not have the headers set by the identifier and dispatcher.\n\nUpdate your service definition in `docker-compose.yml` as follows:\n\n```yml\n    your-microservice-name:\n      ...\n      ports:\n        - 8888:80\n```\n\nNext, recreate the container by executing\n```bash\ndocker-compose up -d your-microservice-name\n```\n\n### Add a dependency to your microservice\nYou can install additional dependencies by including a `package.json` file next to your `app.js`. It works as you would expect: just define the packages in the `dependencies` section of the `package.json`. They will be installed automatically at build time and in development mode. There is no need to restart the container.\n\n### Handle delta's from the delta-service\nIf you are building a reactive service that should execute certain logic based on changes in the database, you want to hook it up to the [delta-notifier](https://github.com/mu-semtech/delta-notifier/). Some extra steps need to be taken to properly handle delta's, specifically the route handling delta's will need to use a specific bodyParser. \n\nThe default bodyParser provided by the template will only accept `application/vnd.api+json` and the delta-notifier is sending `application/json` content. Aside from that the body of a delta message may be very large, often several megabytes. By specifying the bodyParser on the route accepting delta messages you can easily modify it when required.\n\nAn example\n```javascript\n// app.js\nimport bodyParser from 'body-parser';\n// ...\n\napp.post(\"/delta-updates\", bodyParser.json({ limit: '50mb' }), function(req, res) {\n//...\n}\n```\n\n## Reference\n### Framework\nThe mu-javascript-template is built on ExpressJS. Check [Express' Getting Started guide](https://expressjs.com/en/starter/basic-routing.html) to learn how to build a REST API in Express.\n\nThe Express application can be imported from the `'mu'` package as follows:\n```javascript\nimport { app } from 'mu'\n```\n\nRoutes can be defined on the application as explained in the [Express routing guide](https://expressjs.com/en/guide/routing.html). For example:\n\n```javascript\nimport { app } from 'mu'\n\napp.get('/hello', function( req, res ) {\n  res.send('Hello mu-javascript-template');\n} );\n```\n\n### Helpers\nThe template offers some helpers. They can all be imported from the `'mu'` package like\n```\nimport { app, uuid, sparqlEscapeString } from 'mu'\n\napp.get('/', function( req, res ) {\n  const id = uuid();\n  ...\n} );\n```\n\nYou can also import the whole `mu` object like\n```\nimport mu from 'mu';\n\nmu.app.get('/', function( req, res ) {\n  const id = mu.uuid();\n  ...\n} );\n```\n\nThe following helper functions are provided by the template\n  - `query(query) =\u003e Promise`: Function for sending queries to the triplestore\n  - `update(query) =\u003e Promise`: Function for sending updates to the triplestore\n  - `uuid() =\u003e string`: Generates a random UUID (e.g. to construct new resource URIs)\n\nThe following SPARQL escape helpers are provided to construct safe SPARQL query strings\n  - `sparqlEscapeString(value) =\u003e string`\n  - `sparqlEscapeUri(value) =\u003e string`\n  - `sparqlEscapeDecimal(value) =\u003e string`\n  - `sparqlEscapeInt(value) =\u003e string`\n  - `sparqlEscapeFloat(value) =\u003e string`\n  - `sparqlEscapeDate(value) =\u003e string`\n  - `sparqlEscapeDateTime(value) =\u003e string`\n  - `sparqlEscapeBool(value) =\u003e string`: The given value is evaluated to a boolean value in javascript. E.g. the string value `'0'` evaluates to `false` in javascript.\n  - `sparqlEscape(value, type) =\u003e string`: Function to escape a value in SPARQL according to the given type. Type must be one of `'string'`, `'uri'`, `'int'`, `'float'`, `'date'`, `'dateTime'`, `'bool'`.\n\n### Error handling\nThe template offers [an error handler](https://expressjs.com/en/guide/error-handling.html) to send error responses in a JSON:API compliant way. The handler can be imported from `'mu'` and need to be loaded at the end.\n\n```javascript\nimport { app, errorHandler } from 'mu'\n\napp.get('/hello', function( req, res, next ) {\n  try {\n    ...\n  } catch (e) {\n    next(new Error('Oops, something went wrong.))\n  }\n});\n\napp.use(errorHandler)\n```\n\n### Transpiled languages\nThe template has second-class support for transpiling TypeScript and CoffeeScript.  These are considered second-class and support may be removed in a minor release but not in a patch release.\n\nOverwriting files through the config folder may require you to stick to the original format.  There are currently no guarantees on this.\n\n#### Coffeescript\nAny file extending to .coffee will be transpiled from coffeescript to javascript file.  Sourcemaps are included for debugging.\n\n#### TypeScript\nAny file extending in .ts will be transpiled to a javascript file.  Sources are currently not typechecked though this is subject to change.  Sourcemaps are included for debugging.\n\n\n### Configuration\n#### Environment variables\nThe following environment variables can be configured:\n\n  - `NODE_ENV` (default: `production`): either `\"development\"` or `\"production\"`. The environment to start the application in. The application live reloads on changes in `\"development\"` mode.\n  - `MAX_BODY_SIZE` (default: `100kb`): max size of the request body. See [ExpressJS documentation](https://expressjs.com/en/resources/middleware/body-parser.html#limit).\n  - `HOST` (default: `0.0.0.0`): The hostname you want the service to bind to.\n  - `PORT` (default: `80`): The port you want the service to bind to.\n\n\n#### Mounting `/config`\nYou may let users extend the microservice with code.\n\nWhen you import content from `./config/some-file`, the sources can be provided by the end user in `/config/some-file` (even in production mode).\n\nYou may provide default values for each of these files. The sources provided by the app are merged with the sources provided by the microservice, with the app's configuration taking precedence.\n\n### Logging\nThe verbosity of logging can be configured through following environment variables:\n\n- `LOG_SPARQL_ALL`: Logging of all executed SPARQL queries, read as well as update (default `true`)\n- `LOG_SPARQL_QUERIES`: Logging of executed SPARQL read queries (default: `undefined`). Overrules `LOG_SPARQL_ALL`.\n- `LOG_SPARQL_UPDATES`: Logging of executed SPARQL update queries (default `undefined`). Overrules `LOG_SPARQL_ALL`.\n- `DEBUG_AUTH_HEADERS`: Debugging of [mu-authorization](https://github.com/mu-semtech/mu-authorization) access-control related headers (default `true`)\n\nFollowing values are considered true: [`\"true\"`, `\"TRUE\"`, `\"1\"`].\n\n### Custom build commands\nTo execute custom bash statements during the image build (e.g. to install aditional system libraries), provide an `on-build.sh` script in the root of your service. It will be automatically picked up and executed by the Docker build.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmu-semtech%2Fmu-javascript-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmu-semtech%2Fmu-javascript-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmu-semtech%2Fmu-javascript-template/lists"}