c97b13632c
* fix(typings): Remove bogus .d.ts files; add new languages PR #3821 added .d.ts files for every file in msg/json/, but several of these are internal utility files rather than translations, and do not result in a langfile being output by create_messages.py when building langfiles. In the meantime we have added a few new languages that are being published but which have (until now) not had the corresponding type declarations. * feat(build)!: Add exports section to package.json Add an exports stanza to package.json, enumerating existing entrypoints in a new format. - The original main entrypoint, index.js, is removed since the exports section can point directly at node.js or browser.js. - No change made (yet) to other entrypoints (core, blocks, generators); these will be dealt with in a subsequent PR. - The msg/en entrypoint is included in the top-level package.json as an example; entries for all other languages created as part of the packageJSON package task. BREAKING CHANGE: The introduction of an exports stanza means that correctly-behaved tools (node.js, bundlers like webpack, etc.) will only allow importing of the specified entrypoints. Here is the full list of permitted entrypoints that can be imported or required: - blockly - blockly/core - blockly/blocks - blockly/dart - blockly/lua - blockly/javascript - blockly/php - blockly/python - blockly/msg/<lang>, for all supported language codes <lang> (e.g blockly/msg/en, blockly/msg/fr, blockly/msg/de, etc.) If you previously impored any other paths from the blockly package you will need to update your imports. Here are the most common paths that may have been used, and their correct replacements: | If you previously imported: | Import instead: | | -------------------------------- | -------------------------- | | blockly/index.js | blockly | | blockly/node.js | blockly | | blockly/browser.js | blockly | | blockly/blockly.min | This file should only be loaded as a <script>. | | blockly/core.js | blockly/core | | blockly/core-browser.js | blockly/core | | blockly/blockly_compressed.js | blockly/core | | blockly/blocks.js | blockly/blocks | | blockly/blocks_compressed.js | blockly/blocks | | blockly/dart.js | blockly/dart | | blockly/dart_compressed.js | blockly/dart | | blockly/lua.js | blockly/lua | | blockly/lua_compressed.js | blockly/lua | | blockly/javascript.js | blockly/javascript | | blockly/javascript_compressed.js | blockly/javascript | | blockly/php.js | blockly/php | | blockly/php_compressed.js | blockly/php | | blockly/python.js | blockly/python | | blockly/python_compressed.js | blockly/python | | blockly/msg/en.js | blockly/msg/en | * fix(build): Use package-paths (blockly/*) in wrapper imports Use 'blockly/core' instead of './core' when importing core into other wrappers (and similarly for other entries in package.json exports stanza), so that (e.g.) dist/javascript.js won't import dist/core.js (the node.js version that loads jsdom) when being loaded in a browser environment. This fixes an issue where blockly attempts to load jsdom even in browser environments because the browser stanza in package.json, which caused attempts to load core.js to load core-browser.js instead in browser environments, was removed in a previous commit. * refactor(build): Remove unnecessray wrappers Remove pointless wrapper modules that no longer server any purpose; use exports stanza in package.json to point directly to compiled chunks where possible. * refactor(build)!: Eliminate separate browser and node entrypoints Combine scripts/package/browser/index.js (becomes dist/browser.js) and scripts/package/node/index.js (becomes dist/node.js) into a single environment-agnostic index.js. BREAKING CHANGE: Historically, importing the main 'blockly' package would import 'blockly/core', 'blockly/blocks', 'blockly/en' and 'blockly/javascript' - and additionally, in node.js, also import 'blockly/dart', 'blockly/lua', 'blockly/php' and 'blockly/python'. Now the main 'blockly' package entrypoint never loads any of the generator modules. This change has been made because of changes to generator exports made in blockly v9.0.0 that make necessary to always separately import generator modules. Note that this change does not affect loading the blockly package via <script src="https://unpkg.com/blockly"; that continues to load to blockly.min.js, which includes javascript_compressed.js and (due to being loaded as a script) makes it available via Blockly.JavaScript. * refactor(build): Simplify core entrypoint wrapper for node.js Move scripts/package/node/core.js to scripts/package/core-node.js, and have it packaged as dist/core-node.js rather than dist/core.js - without a UMD wrapper, since it will always be loaded as a CJS module. * chore(build): Remove disused packageCommonJS helper * refactor(build): Use subpath pattern (wildcard) for msg/* exports Use a subpath pattern (wildcard) for the msg/* entrypoints, obviating the need for special handling in packageJSON. * fix(tests): Fix node tests run_node_test.js previously directly require()d the dist/blockly.js and dist/javascript.js wrapper module, which no longer exist. Change it to require('blockly-test') (and …blockly-test/javascript) and create a symlink ./node_modules/blocky-test -> dist/ to satisfy this. * fix(build): Add types: and default: entries to exports['./core'] In the 'blockly/core' export: - Replace the browser: entrypoint with a default: one. - Add a types: entrypoint for core.
Blockly
Google's Blockly is a library that adds a visual code editor to web and mobile apps. The Blockly editor uses interlocking, graphical blocks to represent code concepts like variables, logical expressions, loops, and more. It allows users to apply programming principles without having to worry about syntax or the intimidation of a blinking cursor on the command line. All code is free and open source.
Getting Started with Blockly
Blockly has many resources for learning how to use the library. Start at our Google Developers Site to read the documentation on how to get started, configure Blockly, and integrate it into your application. The developers site also contains links to:
Help us focus our development efforts by telling us what you are doing with Blockly. The questionnaire only takes a few minutes and will help us better support the Blockly community.
Installing Blockly
Blockly is available on npm.
npm install blockly
For more information on installing and using Blockly, see the Getting Started article.
Getting Help
- Report a bug or file a feature request on GitHub
- Ask a question, or search others' questions, on our developer forum. You can also drop by to say hello and show us your prototypes; collectively we have a lot of experience and can offer hints which will save you time. We actively monitor the forums and typically respond to questions within 2 working days.
blockly-samples
We have a number of resources such as example code, demos, and plugins in another repository called blockly-samples. A plugin is a self-contained piece of code that adds functionality to Blockly. Plugins can add fields, define themes, create renderers, and much more. For more information, see the Plugins documentation.
Contributing to Blockly
Want to make Blockly better? We welcome contributions to Blockly in the form of pull requests, bug reports, documentation, answers on the forum, and more! Check out our Contributing Guidelines for more information. You might also want to look for issues tagged "Help Wanted" which are issues we think would be great for external contributors to help with.
Releases
We release by pushing the latest code to the master branch, followed by updating the npm package, our docs, and demo pages. If there are breaking bugs, such as a crash when performing a standard action or a rendering issue that makes Blockly unusable, we will cherry-pick fixes to master between releases to fix them. The releases page has a list of all releases.
We use semantic versioning. Releases that have breaking changes or are otherwise not backwards compatible will have a new major version. Patch versions are reserved for bug-fix patches between scheduled releases.
We now have a beta release on npm. If you'd like to test the upcoming release, or try out a not-yet-released new API, you can use the beta channel with:
npm install blockly@beta
As it is a beta channel, it may be less stable, and the APIs there are subject to change.
Branches
There are two main branches for Blockly.
master - This is the (mostly) stable current release of Blockly.
develop - This is where most of our work happens. Pull requests should always be made against develop. This branch will generally be usable, but may be less stable than the master branch. Once something is in develop we expect it to merge to master in the next release.
other branches: - Larger changes may have their own branches until they are good enough for people to try out. These will be developed separately until we think they are almost ready for release. These branches typically get merged into develop immediately after a release to allow extra time for testing.
New APIs
Once a new API is merged into master it is considered beta until the following release. We generally try to avoid changing an API after it has been merged to master, but sometimes we need to make changes after seeing how an API is used. If an API has been around for at least two releases we'll do our best to avoid breaking it.
Unreleased APIs may change radically. Anything that is in develop but not master is subject to change without warning.
Issues and Milestones
We typically triage all bugs within 1 week, which includes adding any appropriate labels and assigning it to a milestone. Please keep in mind, we are a small team so even feature requests that everyone agrees on may not be prioritized.
Good to Know
- Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs
- We test browsers using BrowserStack