{"id":19560010,"url":"https://github.com/plotdb/srcbuild","last_synced_at":"2026-03-02T12:47:37.031Z","repository":{"id":57137275,"uuid":"346991315","full_name":"plotdb/srcbuild","owner":"plotdb","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-19T14:37:29.000Z","size":1335,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-09T18:16:04.626Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"LiveScript","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/plotdb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-12T08:16:57.000Z","updated_at":"2024-06-19T14:36:56.000Z","dependencies_parsed_at":"2023-01-30T18:45:26.547Z","dependency_job_id":null,"html_url":"https://github.com/plotdb/srcbuild","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fsrcbuild","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fsrcbuild/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fsrcbuild/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fsrcbuild/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plotdb","download_url":"https://codeload.github.com/plotdb/srcbuild/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240816908,"owners_count":19862389,"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":[],"created_at":"2024-11-11T05:05:33.371Z","updated_at":"2026-03-02T12:47:31.401Z","avatar_url":"https://github.com/plotdb.png","language":"LiveScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# srcbuild\n\nSource file tree builder.\n\n\n## Usage\n\nsetup a lsp ( livescript + stylus + pug ) watcher:\n\n    require! \u003c[@plotdb/srcbuild]\u003e\n    srcbuild.lsp {base: 'web', i18n: ..., logger: ...}\n\nwhere\n\n - `base`: root dir for `src` and `static` folders. default `.`\n - `i18n`: i18n object.\n - `ignored`: files to be ignored. in [anymatch](https://github.com/micromatch/anymatch)-compatible definition.\n   - by default ['.git']\n - `logger`: optional. for logging output. use `console.log` by default.\n   - sample logger with `pino`:\n\n     require! \u003c[@plotdb/srcbuild pino]\u003e\n     srcbuild.lsp({logger: pino({level: 'debug'})})\n\nThese fields will be passed to all customized builders. Additionally, configurations in builder-specific fields will lso be passed to corresponding customized builders. For example, `bundle` field will be passed to `bundle` builder:\n\n    srcbuild.lsp {bundle: { ... /* this will be passed to bundle builder */ }, ...}\n\nFor `lsp`, there are 4 different builders:\n\n - `lsc`: build `*.ls` from `src/ls` to `static/js`.\n - `stylus`: build `*.styl` from `src/styl` to `static/css`.\n - `pug`: build `*.pug` from `src/pug` to `static`.\n - `bundle`: bundle `css` and `js` files\n\nSee following sections for additional options in custom builders.\n\n\n## Custom Adapter\n\nExtend base builder for a customized builder:\n\n    base = require(\"@plotdb/srcbuild\").base\n\n    mybuild = (opt = {}) -\u003e @init({srcdir: 'src', desdir: 'des'} \u003c\u003c\u003c opt)\n    mybuild.prototype = Object.create(base.prototype) \u003c\u003c\u003c {\n      is-supported: (file) -\u003e return true\n      get-dependencies: (file) -\u003e return []\n      build: (files) -\u003e # build will be called if is supported.\n    }\n\nwith following user-defined functions:\n\n - `is-supported(file)`: return true if `file` is supported by this builder, otherwise return false.\n   - `file`: file name for file to be verified. Relative to cwd.\n - `get-dependencies(file)`: return a list of files that this file depends on.\n   - `file`: same as `is-supported`\n - `build(files)`: should compile / generate target files of given file list `files`.\n   - `files`: a list of objects corresponding to files to be compiled, with following fields:\n     - `file`: path of the file to be built, relative to cwd.\n     - `mtime`: timestamp of the modified time of this file. may be modified time of its dependencies.\n - `purge(files)`: should remove generated files corresponding to files listed in `files`.\n   - `files`: same as `build`.\n - `resolve(file)`: return source file path for given target file `file`.\n   - return null if the given target file can't be derived from any supported source files.\n\nand the common options for `init` are as following:\n\n - `base`: root directory for srcbuild to run.\n - `srcdir`: directory for source files. should be relative to `base`. default `src` if omitted.\n - `desdir`: directory for built files. should be relative to `base`. default `static` if omitted.\n - `logger`: logger for log output. use `console` if omitted.\n - `initScan`: default true. if true, run a directory scanning for files to build when adapter is initing.\n\ncheck `src/ext/lsc.ls` or `src/ext/pug.ls` for example.\n\n\n## Options for custom builder\n\nExcept common options, each builder may support different options:\n\n - `pug`:\n   - `intlbase`: base dir to place i18n files. for example, `intl` part of `/intl/zh-TW/index.html`. default `intl`.\n   - `i18n`: an optional i18n object having the same interface with `i18next`\n     - when provided, enable i18n building with following additional features:\n       - source files will be built to multiple locations based on i18n config, such as `/intl/zh-TW/index.html`.\n       - an additional function `i18n` will be available during pug compilation.\n         - `i18n(text)`: translate `text` based on the `i18n` object provided.\n         - `language()`: return current language. ( e.g., `zh-TW` )\n         - `intlbase(p, lng)`: return a path to given `p`, based on current i18n ( or specified `lng` arg ) setup.\n           - for example, `intlbase('link', 'kr')` may generate `/intl/kr/link`, based on he base dir config.\n         - additionally, a pug filter `i18n` is also available, which can be used like:\n\n             span:i18n translate this text\n   - `noView`: default false. when true, js view files ( generated to `viewdir` ) won't be built.\n   - `viewdir`: default `.view`. a directory for storing prebuilt pug files ( in .js format )\n   - `bundler`: default null. Auto packing will be possible only if this is provided.\n   - `locals`: additional local variables for pug context when compiling.\n - `lsc`:\n   - `useGlslify`: default false. set to true if you need glslify of lsc files.\n     - *NOTE* this is an experiment feature and may be removed ( move to standalone builder ) in the future.\n - `bundle`: bundle options. includes:\n   - `configFile`: json file storing bundle configuration. optional.\n   - `relativePath`: use relative path for paths in config file. default false. possible values:\n     - `false`: all files in `configFile` are relative to current working directory.\n     - `true`: all files in `configFile` are relative to the directory containing `bundle.json`\n     - or, specific a path as the relative root.\n   - `manager`: block manager, optional. required for @plotdb/block bundling.\n     - can be either an `block.manager` object, or ...\n     - a function returning such object which accepts an object with following fields as parameter:\n       - `base`: the base dir of this bundle.\n   - `config`: bundle configuration in following format:\n     {\n       \"css\": {\n         \"name\": [ ... list of files to bundle together ]\n       },\n       \"js\": {\n         ...\n       }\n     }\n - `asset`: for copying asset files.\n   - `ext`: array of file extensions to copy. default `[\"png\", \"gif\", \"jpg\", \"svg\", \"json\"]`\n\nThese options are constructor options for corresponding builder, e.g., for pug builder:\n\n    new pugbuild({ i18n: ... })\n\nWhen using shorthands like `srcbuild.lsp(...)`, you can also specify corresponding option in scope, such as:\n\n    srcbuild.lsp({\n      base: '...', i18n: '...',\n      pug: {intlbase: '...'}\n    });\n\ncommon options will be overwritten by scoped options.\n\n\n## Using custom builders\n\nSend adapters to watcher from `getAdapter()` of each custom builders:\n\n    require! \u003c[@plotdb/srcbuild/dist/watch @plotdb/srcbuild/dist/ext/pug]\u003e\n    pugbuilder = new pug(...)\n    watcher = new watch({adapters: [pugbuilder.getAdapter]})\n\nBy default, watcher watches the current working directory. Change watcher behavior with following constructor options:\n\n - `adapters`: array of adapters to use to handle file change events.\n - `ignored`: array of glob strings to ignore when watching for changes. by default `[\".git\"]`.\n - `root`: directory, or array of directories to watch. by default `[\".\"]`.\n - `logger`: optional. logger object with logging functions such as `info`, `warn` and `error`.\n\n\n## ODB / On demand build\n\nuse `watch.demand(target-file)` to force rebuild by request. e.g.,\n\n    require! \u003c[srcbuild]\u003e\n    watch = srcbuild.lsp!\n\n    # this triggers rebuilding of `web/src/pug/index.pug` file.\n    watch.demand('web/static/index.html').then -\u003e console.log \"built.\"\n\n`target` to `source` file mapping is done by `resolve` function in custom builder, so to use on demand build, `resolve` must be implemented.\n\n\n## i18n\n\nuse `srcbuild.i18n` to quickly setup an `i18next` object:\n\n    require! \u003c[srcbuild]\u003e\n    srcbuild.i18n(options)\n      .then (i18n) -\u003e srcbuild.lsp {i18n}\n\n`options` is passed to `i18next` init function. Additional fields in `options` used by `srcbuild.i18n`:\n\n - `enabled`: true if i18n is enabled. default true\n\n\nWhen i18n object is provided, i18n data can be used in pug files via `i18n` function. e.g.,\n\n    div= i18n(\"my-key\")\n\nwill show `my-key` content defined in locale corresponding `default.yaml`:\n\n    my-key: 這是我的鍵\n\n\nTo use a namespaced key, add `:` before key. For example:\n\n    div= i18n(\"new-ns:another-key\")\n\nwill access to `another-key` in `new-ns.yaml`. Be sure to add your namespace name in `ns` field of i18n option:\n\n    \"i18n\": { ...  \"ns\": [\"default\", \"new-ns\"] }\n\nadditionally, use `intlbase` to wrap path with a i18n based relative path:\n\n    a(href=intlbase('/faq'))\n\n\n## Pug Extension\n\nWhen building, we extend Pug via plugins and filters to support more features.\n\n### Pug include path\n\nUse `@` to include files in modules:\n\n    include @/ldview/dist/ldview.pug\n\nUse `@static` to include files under `static` folder:\n\n    include @static/assets/sample.pug\n\nOther paths starting with `@` are reserved and will cause error when used.\n\n\n### Mixins\n\nuse `script` and `css` builtin mixins to load external script and css files:\n\n    +script({name: \"module-name\", version: \"main\", path: \"somefile.js\"})\n    +css({name: \"module-name\", version: \"main\", path: \"somefile.js\"})\n\nwhere the fields of the parameters:\n\n - `name`: module name\n - `version`: module version. default `main`, if omitted.\n - `path`: path of file to load. default `index.min.js`, if omitted.\n - `defer`: defer execution or not. default `true` if omitted.\n - `async`: async loading or not. default `false` if omitted.\n\nBy default the above script mixin generates a script tag pointing to files under `/assets/lib/\u003cname\u003e/\u003cversion\u003e/\u003cpath\u003e`. You can customize the `/assets/lib/` by calling `libLoader.root(desiredPath)`.\n\n\nAdditionally, you can also use a list of modules:\n\n    +script([\n      {name: \"module-a\", version: \"0.0.1\", path: \"somefile.js\"},\n      {name: \"module-b\", version: \"0.2.1\", path: \"another.js\"},\n      {name: \"module-c\", path: \"with-default-version.js\"},\n      {name: \"module-d\", version: \"with.default.path\" },\n      {name: \"with-defer-async\", defer: false, async: true}\n      {name: \"omit-everything\"},\n    ])\n\nUse the second option object to specify additional parameters, including:\n\n - `pack`: *experimental* *deprecated* default false. Enable auto packing or not.\n   - if true, enable auto packing which trigger bundling automatically to a filename from md5 of all script urls.\n   - require `bundler` option in pugbuild constructor.\n   - doesn't work with external urls.\n   - there are still issues about rebuilding and build from view.\n   - replaced by `bundle` filter, which runs in compile time.\n - `min`: default true. When true, use minimized packed file with pack option.\n\n\n### Filters\n\nFollowing formats and filters are supported:\n\n - `lsc`: transpile content from livescript to JavaScript.\n - `stylus`: transpile content from `stylus` to `CSS`.\n - `md`: transpile content from `markdown` to `HTML`.\n - `bundle`: bundle files including js, css or block. usage sample:\n\n    :bundle(options = {type: \"block\", files: [ { bid }, ...  ]})\n\n\n\n\n### JS functions\n\nFollowing functions are added:\n\n - `md(code)`: convert `markdown` to `HTML`.\n - `yaml(path)`: read `yaml` file and return object. (tentative)\n - `yamls(path)`: read content of `yaml` files under `path` directory. (tentative)\n\n\n### Additional filters / functions\n\nThere are some additional `i18n` filters available if properly configured. See above for more information.\n\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplotdb%2Fsrcbuild","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplotdb%2Fsrcbuild","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplotdb%2Fsrcbuild/lists"}