{"id":27451663,"url":"https://github.com/DO-SAY-GO/graderjs","last_synced_at":"2025-04-15T10:01:54.836Z","repository":{"id":56487626,"uuid":"304600431","full_name":"DO-SAY-GO/graderjs","owner":"DO-SAY-GO","description":"💦 Turn your full-stack NodeJS application into a downloadable cross-platform binary. Also works for SPAs, or regular web-sites. ","archived":false,"fork":false,"pushed_at":"2022-08-20T06:05:22.000Z","size":2859,"stargazers_count":155,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T22:07:44.851Z","etag":null,"topics":["cross-platform","desktop-app","electron-alternative","electron-alternatives","native","nodejs","web-ui"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DO-SAY-GO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":"https://buy.stripe.com/3cs7tEcC53Yv3zG8xb"}},"created_at":"2020-10-16T10:57:45.000Z","updated_at":"2025-04-11T23:24:58.000Z","dependencies_parsed_at":"2022-08-15T19:40:33.933Z","dependency_job_id":null,"html_url":"https://github.com/DO-SAY-GO/graderjs","commit_stats":null,"previous_names":["dosyago/graderjs","c9fe/grader","crisdosyago/graderjs","00000o1/graderjs","do-say-go/graderjs"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DO-SAY-GO%2Fgraderjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DO-SAY-GO%2Fgraderjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DO-SAY-GO%2Fgraderjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DO-SAY-GO%2Fgraderjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DO-SAY-GO","download_url":"https://codeload.github.com/DO-SAY-GO/graderjs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249048737,"owners_count":21204306,"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":["cross-platform","desktop-app","electron-alternative","electron-alternatives","native","nodejs","web-ui"],"created_at":"2025-04-15T10:01:36.140Z","updated_at":"2025-04-15T10:01:54.806Z","avatar_url":"https://github.com/DO-SAY-GO.png","language":"Shell","funding_links":["https://buy.stripe.com/3cs7tEcC53Yv3zG8xb"],"categories":["Shell"],"sub_categories":[],"readme":"\n\u003cp align=center\u003e\n \u003cimg alt=\"Windows Grader app screenshot\" src=https://github.com/crisdosyago/graderjs/raw/master/.readme-assets/wingrader.JPG width=222\u003e\n \u003cimg alt=\"Ubuntu Linux Grader app screenshot\" src=https://github.com/crisdosyago/graderjs/raw/master/.readme-assets/grader.JPG width=222\u003e\n\u003c/p\u003e\n\n# [:sweat_drops: GRaderJS](https://github.com/crisdosyago/graderjs) ![npm downloads](https://img.shields.io/npm/dt/graderjs?label=npm%20downloads) ![version](https://img.shields.io/npm/v/graderjs?label=version) [![visitors+++](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2Fc9fe%2Fgraderjs\u0026count_bg=%2379C83D\u0026title_bg=%23555555\u0026icon=\u0026icon_color=%23E7E7E7\u0026title=%28today%2Ftotal%29%20visitors%2B%2B%2B%20since%20Nov%209%202020\u0026edge_flat=false)](https://hits.seeyoufarm.com) \n\nTurn your full-stack NodeJS application into a downloadable cross-platform binary. Also works for SPAs, or regular web-sites.\n\n## Features that work right out of the box\n\n- Create a downloadable binary for any platform ✔️\n- NodeJS ✔️\n- Chrome DevTools API ✔️\n- GUI in HTML/JavaScript/CSS ✔️\n- BYO front-end framework ✔️\n- BYO back-end framework ✔️\n- A GUI window with OS-default topbar controls that can be dragged, maximized, minimized, resized ✔️\n- A simple API for controlling windows, and interacting with DevTools ✔️\n- GUI window has app title and can have app icon. ✔️\n- ES6 all the latest features (that work in the latest Chrome). ✔️\n- Cross-platform builds (build for everywhere on Linux, or Mac or Windows). ✔️\n\n## Features that don't (yet?) work\n\n- App binary icons (it's just the NodeJS icon) 💀\n- App system tray icons (on Mac, tray icons work on Windows) 💀\n- Code signing and associated bona fides that give apps a \"passport for safe and unimpeded passage\" through your system (it's not built in, but you can sign your own binary, if you have the right setup). 💀\n\n## What are apps built with GraderJS, technically?\n\nA GraderJS app is just a full-stack application written in NodeJS that runs locally on your client's machine. It achieves this by:\n\n- bundling a NodeJS (for the target platform) and your back-end and front-end source code into the binary.\n- on execution the binary:\n  1. starts the back-end service\n  2. unzips the front-end to a temporary directory\n  3. probes the screen to find its dimensions using a silently launched chrome window (and downloads and installs chrome if it is not)\n  4. opens an \"app view\" chrome UI window to display the front-end\n\nGraderJS apps are un-opinionated. You can code the front and back-end however you like, and all details like persisting state to the client's machine, and other useful things, are left to the app author to figure out themselves, and decide which way they want to go.\n\nUnlike a regular full-stack app, GraderJS apps:\n\n1. Look like a native app and run on the desktop.\n2. Have full access to the system.\n3. Have full access to the Chrome DevTools API to be able to fully utilize the great browser APIs, enabling you to incorporate \"browser power\" (think, automation of browsers, but that's just a fraction of what's possible) into your app experiences\n\n## Details\n\nMinimal binary is 50MB (Macos, Hello World App, using node v16.16.0, with executable built by pkg). \n\n\u003cspan id=top\u003e\u003c/span\u003e\n-------------------\n- [Overview](##goggles-graderjs---)\n  * [Details](#details)\n  * [Advantages](#advantages)\n  * [Disadvantages](#disadvantages-or-opportunities-and-opportunities-for-improvement-yes)\n  * [Grader workflow](#grader-workflow)\n  * [Extended Workflow](#extended-workflow)\n  * [Ultimate Workflow](#ultimate-workflow-still-impossible)\n  * [License](#license)\n  * [Built with Grader](#built-with-grader)\n- [Getting Started](#getting-started) \n  * [API \u0026 Documentation](#api--documentation)\n  * [Extraordinary Control](#extraordinary-control)\n  * [NodeJS related](#nodejs-related)\n  * [App lifecycle](#app-lifecycle)\n  * [Window related](#window-related)\n  * [Docketty Docs](#docketty-docs)\n  * [Questions](#questions)\n- [Step by step guide](#step-by-step-guide)\n  * [Get Started from the Command line](#get-started-from-the-command-line)\n  * [Get Started from GitHub](#get-started-from-github)\n  * [Start Building!](#start-building)\n  * [Start Coding](#start-coding)\n- [API](#api)\n- [Then build it](#then-build-it)\n- [Configuration](#configuration)\n- [Screenshots](#screenshots)\n- [More](#more)\n- [Licensing](#licensing)\n- [Related projects](#related-projects)\n--------------------\n\n## Advantages\n\n- Simplicity. Grader is just a web server running on localhost viewed with the user's browser. If they have Chrome installed then you get a proper looking desktop app (thanks to the --app flag), and access to a bunch of cool APIs to control the browser (thanks to remote DevToosl protocol).\n- Extensive APIs. Because you have access to Node.JS and, with Chrome, DevTools APIs there's so many things you can do. You can do almost anything.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Disadvantages (...or, Opportunities, and Opportunities for Improvement? Yes)\n\n- New. Undeveloped. Embryonic. Fragile. Untested. Unknown (relatively).\n- Requires Chrome to be installed for a great experience (some people don't have it).\n- Bundles Node.JS (and packs using upx but the binaries are still bigger than using Tauri or Neutralino).\n- API still undeveloped and likely to change.\n- Icons (for the binary) don't work (and it's a hard problem).\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Grader Workflow \n\n1. Create a new Grader app\n2. Fill out the sections with your business logic and app specific node\n3. Compile to get cross-platform binaries\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Extended Workflow \n\n4. Code-sign your binaries and upload them to app stores or GitHub releases or your own website.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Ultimate Workflow (still impossible)\n\n5. Use ~impossible non-existant~ ~(future?)~ packaging tool to bundle each binary in a soothing bath of platform specific app metadata that includes icons and associated weird OS specific coolness to make things truly awesome.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## License \n\nCopyright (c) 2020, Dosyago and/or its affiliates. All rights reserved.\n\nThis is a release of Grader, an cross-platform app builder.\n\nLicense information can be found in the LICENSE file.\n\nThis software is dual-licensed. For information about commercial licensing, see [Dosyago Commercial License for OEMs, ISVs and VARs](https://github.com/dosyago/dual-licensing).\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Built with Grader\n\n- [wingrader](https://github.com/crisdosyago/winrader) - windows 95 cross platform\n- [jspaint.exe](https://github.com/crisdosyago/jspaint.exe) - classic paint cross platform\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Getting Started\n\n```sh\nnpx graderjs my-app\n```\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### API \u0026 Documentation\n\nOnly a couple of API calls, classed into four categories: Protocol, NodeJS, App, Window.\n\nRead [the API docs](https://github.com/crisdosyago/grader-base) for a detailed usage or see below for an overview.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Protocol Control\n\nInstrument the browser directly with DevTools\\*.\n\n- constrol.send(command, params)\n- control.on(eventName, handlerFunction) (also off)\n\n\\**See commands available at [DevTools protocol homepage](https://chromedevtools.github.io/devtools-protocol/tot/)*\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### NodeJS related\n\n*As normal just use npm to add dependencies and import to use them*\n\n### App Lifecycle\n\n- launch: `go()` \n- shutdown: `stop()`\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Window Related\n\n  - ui.open  \n  - ui.close \n  - ui.move  \n  - ui.size  \n  - ui.minimize \n  - ui.maximize \n  - ui.restore  \n  - ui.fullscreen  \n  - ui.partscreen  \n  - ui.getLayout\n  - ui.openBlank (*not yet implemented*)\n  - ui.writePage (*not yet implemented*)\n  - ui.getScreen\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Docketty Docs\n\nThen, read the [API docs](https://github.com/crisdosyago/grader-base/blob/master/README.md) or see below for the Getting Started Goose Guide.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Questions\n\nOpen an issue!\n  \n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Step By Step Guide\n\n### Get Started from the Command line\n\nUse npm to get the [Grader.JS tool](https://github.com/crisdosyago/graderjs) to automatically populate your new grader app.\n\n```sh\n  $ npm i -g graderjs@latest\n  $ graderjs my-new-app\n```\n\nThen, read the [API docs](https://github.com/crisdosyago/grader-base/blob/master/README.md) or see below for the Getting Started Goose Guide.\n\n*Or...*\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Get Started from GitHub\n\nClick [\"Use This Template\"](https://github.com/crisdosyago/grader-base) on the base-repo and you will have a new repo, then clone it to your workspace and `cd` into it, and run:\n\n```sh\nnpm i\n```\n\n*Then...*\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Start Building!\n\nRead [the API docs](https://github.com/crisdosyago/grader-base), or create yer binaries right away:\n\n```sh\n./scripts/compile.sh\n```\n\nYou now have a GUI app in Node.JS and JavaScript/HTML/CSS.\n\nAnd you will have cross-platform binaries available in `/bin`\n\n(*and also for download from the computer you're on at port 8080.*)\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Start Coding\n\nPut your own code into, `src/app.js`:\n\n**E.g**:\n\n```js\n  import Grader from './index.js';\n\n  start();\n\n  async function start() {\n    await Grader.go();\n  }\n```\n\nAnd put your JS/HTML/CSS into, `src/public/index.html`:\n\n```html\n  \u003cmeta charset=utf-8\u003e\n  \u003ctitle\u003eYour Cross-Platform App\u003c/title\u003e\n  \u003cstyle\u003e\n    :root {\n      font-family: sans-serif;\n      background: lavenderblush;\n    }\n    body {\n      display: table;\n      margin: 0 auto;\n      background: silver;\n      padding: 0.5em;\n      box-shadow: 0 1px 1px purple;\n    }\n    h1 {\n      margin: 0;\n    }\n    h2 {\n      margin-top: 0;\n    }\n  \u003c/style\u003e\n  \u003ch1\u003eHello World!\u003c/h1\u003e\n  \u003ch2\u003eMeet \u003ci\u003eGrader\u003c/i\u003e\u003c/h2\u003e\n  \u003cp\u003e\n    \u003cbutton onclick=\"grader.ui.minimize();\"\u003e_\u003c/button\u003e\n    \u003cbutton onclick=\"grader.ui.restore();\"\u003e\u0026#11036;\u003c/button\u003e\n    \u003cbutton onclick=\"grader.ui.close();\"\u003ex\u003c/button\u003e\n  \u003cscript\u003e\n      (async () =\u003e {\n        await graderReady();\n\n        const [title, favicon, startURL] = (await Promise.allSettled([\n          grader.meta.getTitle(),\n          grader.meta.getFavicon(),\n          grader.meta.getStartURL()\n        ])).map(({status, value, reason}) =\u003e {\n          if ( status == 'fulfilled' ) return value;\n          return reason;\n        });\n\n        console.log({title, favicon, startURL});\n\n        document.title = title;\n      })();\n    \u003c/script\u003e\n```\n\n### API\n\nRead [the API docs](https://github.com/crisdosyago/grader-base)!\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n### Build it\n\n```sh\n./scripts/compile.sh\n```\n\nYou now have a GUI app in Node.JS and JavaScript/HTML/CSS.\n\nAnd you will have cross-platform binaries available in `/bin`\n\nand also for download from the computer you're on at port 8080.\n\nFor more demos see the demos in `src/demos`.\n\n### Configuration\n\nYou can configure some options, via the configuration located in `src/config.js`:\n\n```js\nmodule.exports = {\n  name: \"MyGraderApp\",\n  entry: \"./app.js\",\n  author: {\n    name: \"my name\",\n    url: \"https://github.com/my-github-username\",\n  },\n  desiredPort: 49666,\n  version: \"0.0.1\",\n  description: \"A Beautiful Demonstration\",\n  source: \"https://github.com/my-github-username/MyGraderApp\",\n  organization: {\n    name: \"My Org\",\n    url: \"https://github.com/my-github-org-name\"\n  },\n  apiOrigins: [],      // origins allowed to call API from UI (not implemented)\n  DEBUG: false         // switch on debug output when you're ready to debug\n}\n```\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Screenshots\n\n![Windows Grader](https://github.com/crisdosyago/graderjs/raw/master/.readme-assets/wingrader.JPG)\n![Linux Grader](https://github.com/crisdosyago/graderjs/raw/master/.readme-assets/grader.JPG)\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## More\n\nSee [the API docs](https://github.com/crisdosyago/grader-base) for more. Or just read the README.md of the grader app you've just created, it contains the full API docs. You can also take a look at the API code in `src/index.js`.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Licensing\n\nYou're free to use this so long as you abide by AGPL-3.0. If you want to use it commercially or don't want this license, you can [purchase an exemption](mailto:cris@dosycorp.com?subject=Grader.JS).\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## Related projects\n\nSee [this list of Electron alternatives](https://github.com/sudhakar3697/electron-alternatives) for more options for cross-platform desktop app developement using web technologies.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n## nerding warnung\n\n**WARNING:** This project uses Google Chrome to display the UI. Running this will download and install Google Chrome if you don't already have it installed. If you are allergic to Google Chrome, please avoid running or ingesting this coode.\n\n\u003cp align=right\u003e\u003ca href=#top\u003eTop\u003c/a\u003e\u003c/p\u003e\n\n----------------------\n\n\n# *Grader.JS!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDO-SAY-GO%2Fgraderjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDO-SAY-GO%2Fgraderjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDO-SAY-GO%2Fgraderjs/lists"}