{"id":22423295,"url":"https://github.com/prantlf/concat-source-text","last_synced_at":"2026-05-08T08:11:13.991Z","repository":{"id":57685482,"uuid":"487294138","full_name":"prantlf/concat-source-text","owner":"prantlf","description":"Concatenates text source files and generates a source map for the text output.","archived":false,"fork":false,"pushed_at":"2022-05-01T00:33:57.000Z","size":52,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-12T09:11:35.410Z","etag":null,"topics":["concat","concatenate","css","source","source-map","source-maps","stylesheets","text"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-30T14:10:38.000Z","updated_at":"2023-03-19T18:46:21.000Z","dependencies_parsed_at":"2022-09-19T08:40:45.985Z","dependency_job_id":null,"html_url":"https://github.com/prantlf/concat-source-text","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/prantlf/concat-source-text","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fconcat-source-text","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fconcat-source-text/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fconcat-source-text/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fconcat-source-text/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/concat-source-text/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fconcat-source-text/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32772153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T02:36:36.067Z","status":"ssl_error","status_checked_at":"2026-05-08T02:36:07.210Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["concat","concatenate","css","source","source-map","source-maps","stylesheets","text"],"created_at":"2024-12-05T18:09:55.314Z","updated_at":"2026-05-08T08:11:13.972Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# concat-source-text\n\n[![Latest version](https://img.shields.io/npm/v/concat-source-text)\n ![Dependency status](https://img.shields.io/librariesio/release/npm/concat-source-text)\n](https://www.npmjs.com/package/concat-source-text)\n[![Code coverage](https://codecov.io/gh/prantlf/concat-source-text/branch/master/graph/badge.svg?token=qLsarhf7g7)](https://codecov.io/gh/prantlf/concat-source-text)\n\nConcatenates text source files and generates a source map for the text output. Can be used to concatenate stylesheets and show the original source stylesheets in the debugger. Supports nested source maps and merges them to the final output.\n\n## Synopsis\n\nLet us concatenate text content of two source files:\n\n```js\nimport { SourceTextConcatenator } from 'concat-source-text'\n\nconst concatenator = new SourceTextConcatenator\nconcatenator.append('first content', 'first.txt')\nconcatenator.append('second content', 'second.txt')\nconst { text } = concatenator.join({ sourceMap: true })\nconsole.log(text)\n```\n\nThe console output will be:\n\n    first content\n    second content\n    //# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImZpcnN0LnR4dCIsInNlY29uZC50eHQiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7QUNBQSJ9\n\nAnd the decoded source map content:\n\n```json\n{\"version\":3,\"sources\":[\"first.txt\",\"second.txt\"],\"names\":[],\"mappings\":\"AAAA;ACAA\"}\n```\n\n## Installation\n\nThis module can be installed in your project using [NPM], [PNPM] or [Yarn]. Make sure, that you use [Node.js] version 12 or newer.\n\n```sh\nnpm i concat-source-text\npnpm i concat-source-text\nyarn add concat-source-text\n```\n\n## API\n\n### constructor()\n\nCreates a new empty instance of the concatenator.\n\n### append(contents: string, source: string): void\n\nAppends a text file to the output.\n\n* `contents`: the contents of the file\n* `source`: the name of the file\n\n### join(options?: Options): Output\n\nConcatenates the appended files and returns the complete text with the source map. A line break will be appended after each source text, if the source text does not already end with a line break.\n\n#### Options\n\n* `separator?`: inserts a string between two source files (an empty string (`''`) by default)\n* `sourceMap?`: enables generating the source map (`false` by default)\n\nIf `sourceMap` is set to `true` or to `{}`, it will be converted to `{ inline: true }`. Otherwise an object is expected with the following properties:\n\n#### SourceMap\n\n* `inline?`: appends the source map as a comment to the output text (`true` by default, if `external` is not `true`)\n* `external?`: appends a comment to the output text pointing to an external file with the source map (`false` by default)\n* `separate?`: disables source map generation if set to `false` together with `inline`\n* `outputFile?`: sets a name of the output file to the source map\n* `mapFile?`: set the name of the external source map file in the comment\n* `sourcesContent?`: includes the content of the source files in the source map\n* `multilineComment?`: uses the multi-line comment (`/**# ... */`) instead of the single-line one (`//# ...`), which is the default\n* `readSourceMaps?`: checks existence and reads source maps from input sources if detected\n* `mapDir?`: directory to read a source map file from\n* `locateSourceMap?`: returns directory to read a source map file from\n\nIf both `inline` and `external` are set to `true`, `external` will be chosen and `inline` considered unset. If `inline` is set to `false` and `external` unset or set to `false`, a separate source map will be returned, but no comment will be appended to the output text.\n\nIf `mapFile` is not provided and it is needed for the comment, it will be computed from `outputFile` by appending \".map\" to it.\n\nSetting `separate` can be used to strip source maps from the source files, if they are expected there: `{ inline: false, separate: false, readSourceMaps: true }`.\n\nIf the source map file is lot located on the path stored in the comment, usually resolved from the current directory, you can supply the directory by `mapDir`, or by a callback `locateSourceMap(mapFile: string, source: string): string | undefined`:\n\n* `mapFile`: the name of the source map file parsed from the comment\n* `source`: the name of the source, which the source map belongs to\n\n#### Output\n\n* `text`: the concatenated text\n* `map?`: the source map, if `sourceMap` was set and was not `false`\n\n## Example - CSS\n\nLet us concatenate two stylesheets:\n\nbase.css:\n\n```css\nbody { padding: 1rem }\n```\n\nwidget.css:\n\n```css\n.container { display: flex }\n```\n\nBy the following script:\n\n```js\nimport { readFile, writeFile } from 'fs/promises'\nimport { SourceTextConcatenator } from 'concat-source-text'\n\nconst concatenator = new SourceTextConcatenator\nconcatenator.append(await readFile('base.css', 'utf8'), 'base.css')\nconcatenator.append(await readFile('widget.css', 'utf8'), 'widget.css')\nconst { text, map } = concatenator.join({\n  separator: '\\n',\n  sourceMap: {\n    external: true,\n    mapFile: 'main.css.map',\n    sourcesContent: true,\n    multilineComment: true\n  }\n})\nawait writeFile('main.css', text)\nawait writeFile('main.css.map', JSON.stringify(map))\n```\n\nThen the result will be:\n\nmain.css:\n\n```css\nbody { padding: 1rem }\n\n.container { display: flex }\n/*# sourceMappingURL=main.css.map */\n```\n\nmain.css.map:\n\n```json\n{\n  \"version\": 3,\n  \"sources\": [\"base.css\", \"widget.css\"],\n  \"names\": [],\n  \"mappings\": \"AAAA;AACA;;ACDA\",\n  \"sourcesContent\": [\"body { padding: 1rem }\\n\", \".container { display: flex }\"]\n}\n```\n\n## Example - LESS\n\nLet us concatenate two stylesheets:\n\nbase.css:\n\n```css\nbody { padding: 1rem }\n```\n\nwidget.css:\n\n```less\n.widget {\n  background-color: #ddd;\n}\n.widget-active {\n  background-color: #888;\n}\n/*# sourceMappingURL=widget.css.map */\n```\n\nwidget.css.map:\n\n```json\n{\n  \"version\": 3,\n  \"sources\": [\"widget.less\"],\n  \"names\": [],\n  \"mappings\": \"AAGA;EACE,sBAAA;;AAEA,OAAC;EACC,sBAAA\",\n  \"file\": \"widget.css\",\n  \"sourcesContent\": [\"@color-normal: #ddd;\\n@color-active: #888;\\n\\n.widget {\\n  background-color: @color-normal;\\n\\n  \u0026-active {\\n    background-color: @color-active;\\n  }\\n}\\n\"]\n}\n```\n\nBy the following script:\n\n```js\nimport { readFile, writeFile } from 'fs/promises'\nimport { SourceTextConcatenator } from 'concat-source-text'\n\nconst concatenator = new SourceTextConcatenator\nconcatenator.append(await readFile('base.css', 'utf8'), 'base.css')\nconcatenator.append(await readFile('widget.css', 'utf8'), 'widget.css')\nconst { text, map } = concatenator.join({\n  separator: '\\n',\n  sourceMap: {\n    external: true,\n    outputFile: 'main.css',\n    sourcesContent: true,\n    multilineComment: true,\n    readSourceMaps: true\n  }\n})\nawait writeFile('main.css', text)\nawait writeFile('main.css.map', JSON.stringify(map))\n```\n\nThen the result will be:\n\nmain.css:\n\n```css\nbody { padding: 1rem }\n\n.widget {\n  background-color: #ddd;\n}\n.widget-active {\n  background-color: #888;\n}\n/*# sourceMappingURL=main.css.map */\n```\n\nmain.css.map:\n\n```json\n{\n  \"version\": 3,\n  \"sources\": [\"base.css\", \"widget.less\"],\n  \"names\": [],\n  \"mappings\": \"AAAA;;ACGA;EACE,sBAAA;;AAEA,OAAC;EACC,sBAAA\",\n  \"file\": \"main.css\",\n  \"sourcesContent\": [\"body { padding: 1rem }\",\"@color-normal: #ddd;\\n@color-active: #888;\\n\\n.widget {\\n  background-color: @color-normal;\\n\\n  \u0026-active {\\n    background-color: @color-active;\\n  }\\n}\\n\"]\n}\n```\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.\n\n## License\n\nCopyright (c) 2022 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[Node.js]: http://nodejs.org/\n[NPM]: https://www.npmjs.com/\n[PNPM]: https://pnpm.io/\n[Yarn]: https://yarnpkg.com/\n[@prantlf/convert-source-map]: https://www.npmjs.com/package/@prantlf/convert-source-map\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fconcat-source-text","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fconcat-source-text","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fconcat-source-text/lists"}