{"id":17676349,"url":"https://github.com/stylet/tailorx","last_synced_at":"2025-08-21T04:31:16.110Z","repository":{"id":41986417,"uuid":"237005071","full_name":"StyleT/tailorx","owner":"StyleT","description":"A streaming layout service for front-end microservices used in Isomorphic Layout Composer","archived":false,"fork":false,"pushed_at":"2022-08-26T10:19:08.000Z","size":803,"stargazers_count":67,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-09T17:02:11.556Z","etag":null,"topics":["fragment-server","frontend","microfrontends","microservices","page-composition"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StyleT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-29T14:42:58.000Z","updated_at":"2025-07-01T22:28:09.000Z","dependencies_parsed_at":"2022-08-12T01:30:41.920Z","dependency_job_id":null,"html_url":"https://github.com/StyleT/tailorx","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/StyleT/tailorx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StyleT%2Ftailorx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StyleT%2Ftailorx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StyleT%2Ftailorx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StyleT%2Ftailorx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StyleT","download_url":"https://codeload.github.com/StyleT/tailorx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StyleT%2Ftailorx/sbom","scorecard":{"id":135116,"data":{"date":"2025-08-11","repo":{"name":"github.com/StyleT/tailorx","commit":"44d13e0288d675061aece19e201503260d1339dc"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.2,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":5,"reason":"Found 8/16 approved changesets -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 22 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-16T06:18:58.351Z","repository_id":41986417,"created_at":"2025-08-16T06:18:58.351Z","updated_at":"2025-08-16T06:18:58.351Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271425073,"owners_count":24757404,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["fragment-server","frontend","microfrontends","microservices","page-composition"],"created_at":"2024-10-24T07:25:18.857Z","updated_at":"2025-08-21T04:31:15.816Z","avatar_url":"https://github.com/StyleT.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![TailorX logo](./logo/tailorx-logo.png)\n\n---\n\n[![NPM](https://nodei.co/npm/tailorx.png)](https://npmjs.org/package/tailorx)\n[![Build Status](https://travis-ci.com/StyleT/tailorx.svg?branch=master)](https://travis-ci.com/StyleT/tailorx)\n[![Test Coverage](https://codecov.io/github/StyleT/tailorx/coverage.svg?precision=0)](https://codecov.io/github/StyleT/tailorx)\n[![OpenTracing Badge](https://img.shields.io/badge/OpenTracing-enabled-blue.svg)](http://opentracing.io)\n\n## npm status\n\n[![downloads](https://img.shields.io/npm/dt/tailorx.svg)](https://npmjs.org/package/tailorx)\n[![version](https://img.shields.io/npm/v/tailorx.svg)](https://npmjs.org/package/tailorx)\n\nTailorX is a layout service that uses streams to compose a web page from fragment services.\nO'Reilly describes it in the title of\n[this blog post](https://www.oreilly.com/ideas/better-streaming-layouts-for-frontend-microservices-with-tailor)\nas \"a library that provides a middleware which you can integrate into any Node.js server.\"\nIt's partially inspired by Facebook’s [BigPipe](https://www.facebook.com/notes/facebook-engineering/bigpipe-pipelining-web-pages-for-high-performance/389414033919/)\nand based on [Zalando Tailor](https://github.com/zalando/tailor).\n\nSome of TailorX's features and benefits:\n\n* **Composes pre-rendered markup on the backend**. This is important for SEO and fastens the initial render.\n* **Ensures a fast Time to First Byte**. TailorX requests fragments in parallel and streams them as soon as possible, without blocking the rest of the page.\n* **Enforces performance budget**. This is quite challenging otherwise, because there is no single point where you can control performance.\n* **Fault Tolerance**. Render the meaningful output, even if a page fragment has failed or timed out.\n\nTailorX is part of [Isomorphic Layout Composer Project](https://github.com/StyleT/icl), which aims to help developers create microservices for the frontend. If your front-end team is making the monolith-to-microservices transition, you might find TailorX and its available siblings beneficial.\n\n## Why a Layout Service?\n\nMicroservices get a lot of traction these days. They allow multiple teams to work independently from each other, choose their own technology stacks and establish their own release cycles. Unfortunately, frontend development hasn’t fully capitalized yet on the benefits that microservices offer. The common practice for building websites remains “the monolith”: a single frontend codebase that consumes multiple APIs.\n\nWhat if we could have microservices on the frontend? This would allow frontend developers to work together with their backend counterparts on the same feature and independently deploy parts of the website — “fragments” such as Header, Product, and Footer. Bringing microservices to the frontend requires a layout service that composes a website out of fragments. Tailor was developed to solve this need.\n\n## Installation\n\nBegin using TailorX with:\n\n```sh\nnpm i tailorx\n```\n\n```javascript\nconst http = require('http');\nconst Tailor = require('tailorx');\nconst tailor = new Tailor({/* Options */});\nconst server = http.createServer(tailor.requestHandler);\nserver.listen(process.env.PORT || 8080);\n```\n\n## Options\n\n* `fetchContext(request)` - Function that returns a promise of the context, that is an object that maps fragment id to fragment url, to be able to override urls of the fragments on the page, defaults to `Promise.resolve({})`\n* `fetchTemplate(request, parseTemplate)` - Function that should fetch the template, call `parseTemplate` and return a promise of the result. Useful to implement your own way to retrieve and cache the templates, e.g. from s3.\nDefault implementation [`lib/fetch-template.js`](./lib/fetch-template.js) fetches the template from  the file system\n* `templatesPath` - To specify the path where the templates are stored locally, Defaults to `/templates/`\n* `fragmentTag` - Name of the fragment tag, defaults to `fragment`\n* `handledTags` - An array of custom tags, check [`tests/handle-tag`](./tests/handle-tag.js) for more info\n* `baseTemplatesCacheSize` - It is off by default. This cache can speed up parsing base templates. You need to specify it as a number of your base templates to cache the parsing of your templates but don't specify it less than the number of templates that your app has because when you are going to change your template several times without server rebooting than all these changed template's versions are going to be saved on your server which is causing cache issues.\n* `handleTag(request, tag, options, context)` - Receives a tag or closing tag and serializes it to a string or returns a stream\n* `filterRequestHeaders(attributes, request)` - Function that filters the request headers that are passed to fragment request, check default implementation in [`lib/filter-headers`](./lib/filter-headers.js)\n* `filterResponseHeaders(attributes, headers)` - Function that maps the given response headers from the primary \u0026 `return-headers` fragments to the final response\n* `maxAssetLinks` - Number of `Link` Header directives for CSS and JS respected per fragment - defaults to `1`\n* `requestFragment(filterHeaders, processFragmentResponse)(url, attributes, request)` - Function that returns a promise of request to a fragment server, check the default implementation in [`lib/request-fragment`](./lib/request-fragment.js)\n* `processFragmentResponse(response, context): response` - Function that processes response from the fragment. Returns response or throws an error. Check the default implementation in [`lib/process-fragment-response`](./lib/process-fragment-response.js)\n* `tracer` - Opentracing [compliant Tracer implementation](https://doc.esdoc.org/github.com/opentracing/opentracing-javascript/class/src/tracer.js~Tracer.html).\n* `botsGuardEnabled` - `false` by default. This option forces TailorX to respond with 500 error code even if non-primary fragment fails in case the request comes from SEO/SM bot.\nBot detection is done via [device-detector-js](https://www.npmjs.com/package/device-detector-js).\n* `fragmentHooks` - Allows to override default behaviour of the `insertStart` \u0026 `insertEnd` hooks \u0026 wrap response from the fragment with custom code.\n    * `insertStart(stream, attributes, headers, index)`\n    * `insertEnd(stream, attributes, headers, index)`\n* `getAssetsToPreload()` - If specified, should return array of assets that should be added to the response `Link` header for preload.\nReturn value format: `{styleRefs: ['https://ex.com/style.css'], scriptRefs: ['https://ex.com/script.js']}`\n* `shouldSetPrimaryFragmentAssetsToPreload` - `true` by default. This option allows or disallows TailorX to set a primary fragment's assets to the response `Link` header for preload.\n\n## Template\n\nTailorX uses [parse5](https://github.com/inikulin/parse5/) to parse the template, where it replaces each `fragmentTag` with a stream from the fragment server and `handledTags` with the result of `handleTag` function.\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cscript type=\"fragment\" src=\"http://assets.domain.com\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cfragment src=\"http://header.domain.com\"\u003e\u003c/fragment\u003e\n    \u003cfragment src=\"http://content.domain.com\" primary\u003e\u003c/fragment\u003e\n    \u003cfragment src=\"http://footer.domain.com\" async\u003e\u003c/fragment\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Fragment attributes\n\n* `id` - optional unique identifier (autogenerated)\n* `src` - URL of the fragment\n* `primary` - denotes a fragment that sets the response code of the page\n* `timeout` - optional timeout of fragment in milliseconds (default is 3000)\n* `async` - postpones the fragment until the end of body tag\n* `public` - to prevent TailorX from forwarding filtered request headers from upstream to the fragments.\n* `return-headers` - makes TailorX to wait for the fragment response headers \u0026 send them in response.\nNote that they will be merged with headers from `primary` fragment \u0026 may be overwritten by it.\n* `forward-querystring` - forwards query parameters from the original request down to the fragment\n* `ignore-invalid-ssl` - makes TailorX to ignore invalid SSL certificates while requesting a fragment information from an HTTPS server (default is `false`)\n\n\u003e Other attributes are allowed and will be passed as well to relevant functions (eg. `filterRequestHeaders`, `filterResponseHeaders`, etc.)\n\n### Fragment server\n\nA fragment is an http(s) server that renders only the part of the page and sets `Link`, `x-head-title`, `x-head-meta`\nheaders (valid only for primary fragment) to provide urls to CSS and JavaScript resources.\n\nPrimary fragment possible response headers:\n* `Link` - Check [reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link).\n* `x-head-title` - Page title encoded with base64. Will be injected onto `\u003chead\u003e` tag.\nEx: `Buffer.from('\u003ctitle\u003ePage title\u003c/title\u003e', 'utf-8').toString('base64')`\n* `x-head-meta` - Page [meta tags](https://www.w3schools.com/tags/tag_meta.asp) encoded with base64.\nEx: `Buffer.from('\u003cmeta name=\"description\" content=\"Free Web tutorials\"\u003e\u003cmeta name=\"keywords\" content=\"HTML,CSS,XML,JavaScript\"\u003e', 'utf-8').toString('base64')`\n\nCheck [`examples/basic-css-and-js/index.js`](./examples/basic-css-and-js/index.js) for a draft implementation.\n\nA JavaScript of the fragment is an AMD module, that exports an `init` function, that will be called with DOM element of the fragment as an argument.\n\nTailorX will not follow redirects even if fragment response contains 'Location' Header, that is on purpose as redirects can introduce unwanted latency. Fragments with the attribute `primary` can do a redirect since it controls the status code of the page.\n\n**Note: For compatability with AWS the `Link` header can also be passed as `x-amz-meta-link`**\n\n### Passing information to fragments\n\nBy default, the incoming request will be used to selecting the template.\n\nSo to get the `index.html` template you go to `/index`.\n\nIf you want to listen to `/product/my-product-123` to go to `product.html` template, you can change the `req.url` to `/product`.\n\nEvery header is filtered by default to avoid leaking information, but you can give the original URI and host by adding it to the headers, `x-request-host` and `x-request-uri`, then reading in the fragment the headers to know what product to fetch and display.\n\n```javascript\nhttp\n    .createServer((req, res) =\u003e {\n        req.headers['x-request-uri'] = req.url\n        req.url = '/index'\n\n        tailor.requestHandler(req, res);\n    })\n    .listen(8080, function() {\n        console.log('Tailor server listening on port 8080');\n    });\n```\n\n### Concepts\n\nSome of the concepts in TailorX are described in detail on the specific docs.\n\n* [Events](./docs/Events.md)\n* [Base Templates](./docs/Base-Templates.md)\n* [Hooks](./docs/hooks.md)\n* [Performance](./docs/Performance.md)\n\n## OpenTracing\n\nTailorX has out of the box distributed tracing instrumentation with [OpenTracing](https://opentracing.io).\nIt will pick up any span context on the ingress HTTP request and propagate it to the existing\nRemote Procedure Calls (RPCs).\n\nCurrently, only the fetching of fragments is instrumented providing some additional details like the\nfragment tag, attributes and some logging payload like the stack trace for errors.\n\n## Examples\n\n* Basic - `node examples/basic`\n* CSS and JS - `node examples/basic-css-and-js`\n* Multiple Fragments and AMD - `node examples/multiple-fragments-with-custom-amd`\n* Fragment Performance - `node examples/fragment-performance`\n\nGo to [http://localhost:8080/index](http://localhost:8080/index) after running the specific example.\n\n**Note: Please run the examples with node versions \u003e 12.0.0**\n\n## Benchmark\n\nTo start running benchmark execute `npm run benchmark` and wait for couple of seconds to see the results.\n\n## Contributing\n\nPlease check the Contributing guidelines [here](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstylet%2Ftailorx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstylet%2Ftailorx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstylet%2Ftailorx/lists"}