{"id":15012456,"url":"https://github.com/microsoft/pxt-mkc","last_synced_at":"2025-11-05T00:03:00.277Z","repository":{"id":40292188,"uuid":"208160482","full_name":"microsoft/pxt-mkc","owner":"microsoft","description":"Command line tool for MakeCode editors","archived":false,"fork":false,"pushed_at":"2025-03-28T21:19:03.000Z","size":628,"stargazers_count":15,"open_issues_count":28,"forks_count":7,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-06-13T00:12:39.733Z","etag":null,"topics":["makecode","pxt"],"latest_commit_sha":null,"homepage":"https://microsoft.github.io/pxt-mkc/","language":"TypeScript","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/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-12T23:05:32.000Z","updated_at":"2025-05-16T12:50:26.000Z","dependencies_parsed_at":"2023-02-08T20:30:36.361Z","dependency_job_id":"bae39c80-bcb1-431a-9916-cddae32b21bc","html_url":"https://github.com/microsoft/pxt-mkc","commit_stats":{"total_commits":308,"total_committers":11,"mean_commits":28.0,"dds":0.6136363636363636,"last_synced_commit":"d246f4ecd76fde9ea9a7c5e92d2ab9ede5ab2bbe"},"previous_names":[],"tags_count":100,"template":false,"template_full_name":null,"purl":"pkg:github/microsoft/pxt-mkc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fpxt-mkc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fpxt-mkc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fpxt-mkc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fpxt-mkc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/pxt-mkc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fpxt-mkc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259935602,"owners_count":22934386,"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":["makecode","pxt"],"created_at":"2024-09-24T19:42:39.724Z","updated_at":"2025-11-05T00:03:00.271Z","avatar_url":"https://github.com/microsoft.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MKC - command line tool for MakeCode editors\n\nThis package includes a tool that can compile MakeCode (PXT) projects by\ndownloading parts of a released MakeCode web app and running them in node.js.\n\nThis is different than `pxt` command line tool, which is used primarily during\ndevelopment of MakeCode editors.\n\n## Installation\n\nMake sure to install [node.js](https://nodejs.org/).\n\nTo install `mkc` globally, run\n\n```bash\nnpm install -g makecode\n```\n\n**Do not install the npm `mkc` package, it is another package.**\n\nTo update mkc,\n\n```bash\nnpm install -u -g makecode\n```\n\n## Usage\n\nThe command line tool can be invoked as **`makecode`** or **`mkc`** for short.\n\n### mkc init\n\nTo start a new [micro:bit](https://makecode.microbit.org) project in an empty folder:\n\n```bash\nmkc init microbit\n```\n\nwhere `microbit` is the template name. To get the list of supported templates, do `mkc help init`.\n\nIt is possible to specify a list of dependencies to be added to the template.\n\n```bash\nmkc init microbit jacdac jacdac-button jacdac-led\n```\n\nYour project is ready to be edited. If you are a Visual Studio Code user, type `code .` and you're ready to go!\n\n### mkc install\n\nThis command downloads the sources of extensions to the file system so that your TypeScript\nIDE can use them\n\n```bash\nmkc install\n```\n\n### mkc build\n\nIn a folder with `pxt.json` file, run the build command.\n\n```bash\nmkc build\n```\n\nBuild is also the default command, so you can just leave it out.\n\n```bash\nmkc\n```\n\nYou can also pass `--hw f4`, `--hw d5` etc. Try `--hw help` to get a list.\nUse `mkc -j` to build JavaScript (it defaults to native).\n\nTo build and deploy to a device add `-d`.\n\n```bash\nmkc -d\n```\n\nThe tool checks once a day if the MakeCode editor has been updated. However, you can force an update by using `--update`\nduring a build.\n\n```bash\nmkc --update\n```\n\n#### mkc build --watch\n\nUse `--watch`, or `-w`, with `mkc build` to automatically watch changes in source files and rebuild automatically.\n\n```bash\nmkc -w\n```\n\n#### mkc build compile switches\n\nOptions can be passed to PXT compiler using `--compile-flags` (`-f`) option:\n\n```bash\nmkc -f size            # generate .csv file with function sizes\nmkc -f asmdebug        # generate more comments in assembly listing\nmkc -f profile         # enable profiling counters\nmkc -f rawELF          # don't generate .UF2 but a raw ELF file\nmkc -f size,asmdebug   # example with two options\n```\n\nThe same options (except for `asmdebug`) can be passed to website with `?compiler=...` or `?compile=...` argument\nand to the regular `pxt` command line utility with `PXT_COMPILE_SWITCHES=...`.\n\n#### Built files in containers, GitHub Codespace, ...\n\nTo access the build files from a remote machine,\n\n-   open Visual Studio Code\n-   browse to the `built` folder\n-   right click `Download` on the desired file.\n\n### mkc serve\n\nUse `mkc serve` to start a watch-build and localhost server with simulator.\nDefaults to http://127.0.0.1:7001\n\n```bash\nmkc serve\n```\n\nYou can change the port using `port`. \n\n```bash\nmkc serve --port 7002\n```\n\nBy default, the simulator ignores `loader.js`. If you have modifications in that file, use ``--force-local`` to use your `loader.js`.\n\n```bash\nmkc serve --force-local\n```\n\n### mkc clean\n\nRun the clean command to erase build artifacts and cached packages.\n\n```bash\nmkc clean\n```\n\n### mkc search\n\nSearch for extensions hosted on GitHub.\n\n```bash\nmkc search jacdac\n```\n\nYou can use the result with the `add` command to add extensions to your project.\n\n### mkc add\n\nAdds a new dependency to the project. Pass a GitHub repository URL to the `add` command.\n\n```bash\nmkc add https://github.com/microsoft/pxt-jacdac/button\n```\n\nFor Jacdac extensions, simply write `jacdac-servicename`\n\n```bash\nmkc add jacdac-button\n```\n\n### mkc bump\n\nInteractive update of the version number of the current project\nand all nested projects in a mono-repo.\n\n```bash\nmkc bump\n```\n\nUse `--major`, `--minor`, `--patch` to automatically increment the version number.\n\n```bash\nmkc bump --patch\n```\n\nAdding `--version-file` will make `mkc` write a TypeScript file with the version number.\n\n```bash\nmkc bump --version-file version.ts\n```\n\nAdd `--stage` to test the bump without pushing to git.\n\n```bash\nmkc bump --stage\n```\n\n### mkc download\n\nDownloads a shared MakeCode project to files and initializes the project.\n\n```bash\nmkc download https://.....\n```\n\n## Advanced Configuration\n\nThe `init` commands creates a `mkc.json` file that you can also use for additional configurations.\n\n```json\n{\n    \"targetWebsite\": \"https://arcade.makecode.com/beta\",\n    \"hwVariant\": \"samd51\",\n    \"links\": {\n        \"jacdac\": \"../../pxt-jacdac\"\n    },\n    \"overrides\": {\n        \"testDependencies\": {}\n    },\n    \"include\": [\"../../common-mkc.json\"]\n}\n```\n\nAll fields are optional.\n\n-   **targetWebsite** says where to take the compiler from; if you omit it, it will be guessed based on packages used by `pxt.json`;\n    you can point this to a live or beta version of the editor, as well as to a specific version (including SHA-indexed uploads\n    generated during PXT target builds)\n-   **hwVariant** specifies default hardware variant (currently only used in Arcade); try `--hw help` command line option to list variants\n-   **links** overrides specific packages; these can be github packages or built-in packages\n-   **overrides** is used to override specific keys in `pxt.json`\n-   files listed in **include** are merged with the keys from the later ones overriding the keys from the earlier ones;\n    the keys from the current file override all included keys\n\nYou can use `--config-path` or `-c` to build for a different configuration.\n\n```bash\nmkc -c mkc-arcade.json\n```\n\n## Local development\n\nThis section describes how to build mkc itself.\n\nmkc is split into three packages:\n\n1. makecode-core - which contains most of the functionality/shared code\n2. makecode-node - which contains the node CLI (this is the package that is installed via `npm install makecode`)\n3. makecode-browser - which contains a browser implementation of the mkc language service\n\n### Building\n \n-   install node.js\n-   run `npm install` from the root of this repo (this will also link the local packages)\n-   start the build watch in makecode-core and makecode-node:\n    - (run these in separate terminals) \n    - `cd packages/makecode-core \u0026\u0026 npm run watch`\n    - `cd packages/makecode-node \u0026\u0026 npm run watch`\n-   run `node path/to/pxt-mkc/packages/makecode-node/makecode` in your project folder\n\nIf you want to test out changes in pxt, first run the build as usual, and then replace\n`$HOME/.pxt/mkc-cache/https_58__47__47_\u003cyour-editor\u003e-pxtworker.js`\nwith `pxt/built/web/pxtworker.js`.\nMake sure to run `makecode` tool without the `-u` option.\n\n### Releases\n\nTo release a package, run the following script to create+push a tagged release:\n\n```\nnode ./scripts/release.js bump makecode-core\n```\n\nAfter bumping core, to update the CLI package\n- update the core version in the package.json of makecode-node \n- then `node ./scripts/release.js bump makecode-node`\n\n### Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fpxt-mkc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fpxt-mkc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fpxt-mkc/lists"}