Hi, my name is Maribeth and this talk is called "Blockly on npm".
In this talk I'm going to explain what npm is and why you should consider using it in your project.
Then I'll show you how to use Blockly with npm.
I won't be going in depth about how to set up the tools I talk about because that is dependent on
you and your project, but I do have some resources at the end for you to check out afterward.
The first question is what is npm?
npm is the node package manager. It's an open source tool to manage your project's dependencies.
Javascript modules can be published to the npm registry and used by others. We publish
Blockly as an npm package as well as a number of plugins located in Blockly Samples. npm can
do other things too but this is the main focus of this talk. When using npm, you'll have a project
specification called package.json. Here you'll specify your dependencies and their versions in
this example we're saying we need the package called Blockly at or above version 4.20201217.0
Then we can run npm install and npm will go out and fetch a version of Blockly that matches.
There's more to it than that but that's the general idea.
Also there are other package managers that aren't npm. Blockly is also available on yarn and there
are still others I'm only going to talk about npm but the principles are the same for the others.
Next is why you should use it? If you're not using a package manager then you're probably
doing something like forking Blockly, or cloning it, downloading it, etc. Then you modify it
as needed. It's your copy - you can access private apis if you want we can't stop you.
Then you include the files on your web page with a script tag.
This might seem fine for now but it does have some drawbacks.
First of all when you forked Blockly you got whatever the most recent version was,
but we release a new version every quarter. Do you have a plan for keeping your version up to date?
If you don't update you're missing out on bug fixes, new features, new apis, and more. And
yes it's possible to update Blockly yourself by downloading a new version. But there's no built-in
way to do this and you'll have to manually deal with merges, updating your version control,
and so on, not to mention remembering to check for new versions in the first place. With npm ,you can
install a new version with just one npm install command and you're good to go. There are other
problems with the traditional model. You'll have to check the entire Blockly library into source
code. If you're using other libraries you'll have to include those too. That gets messy, it confuses
your version history, and upgrading to a new version can involve complicated merges. With npm
you only have to check in the package.json. When someone downloads your project, they download
that file and they can install the exact same versions of your dependencies for themselves.
If you're using multiple libraries,
those libraries might themselves have dependencies that you have to deal with.
You have to manually make sure you've got all of the correct dependencies and are including them in
your script tags in the correct order. But when you install a dependency with npm, it will also
install all of its dependencies for you and if you're manually managing all of your dependencies,
then you're missing out on some helpful tools. For example one of the tools that the Blockly
team uses automatically alerts us to security vulnerabilities in our dependencies and helps us
update to newer patched versions. There are many other tools out there that interface with npm.
You might be thinking "okay this sounds useful but why does the Blockly team care how I manage
my dependencies?" We care because we want you to be on the latest version of Blockly.
We want you to use the apis and features we built for you. It makes it easier for us to support you
and help you build the features you want to build if you have access to our latest apis.
And it's easiest for you to stay current if you're using a package manager.
And we want you to avoid monkey patching as much as possible. Monkey patching is generally
bad because it's fragile if you're changing some internal function of Blockly there's no guarantee
that it will continue to work in future updates. In this example of monkey patching we've changed
the behavior of a protected function right inside the core Blockly files that were downloaded.
We're creating a merge conflict we'll have to resolve when we update
,and it can be hard to keep track of what code we added or changed from the original.
This is a slightly better example.
We're still patching Blockly but in our own application code so we won't have
merge conflicts and it will be easier to keep track of where we've created custom behavior.
But the best way is to use only the public apis to add your custom behavior.
In this example we've created our own custom toolbox class and registered it via the option
struct that we pass in to Blockly.inject. There's no patching involved at all. And updating to a new
version shouldn't break the toolbox. If you're not sure if your customization can be achieved
without patching, ask us! We are working on additional APIs so let us know what you need.
Of course you don't have to use npm to follow this pattern.
You should follow it anyway even if you're not using npm,
but using a package manager creates a natural separation between your application code and
the Blockly code, and it removes the temptation to just add one little thing to the Blockly codebase.
Now if I've convinced you that using a package manager could be
helpful to your project you might be wondering how to go about using it.
This is the full process of using packages in your code.
First you would install Blockly with npm; then you would transpile your code to es5 syntax
if that's desired for your project or you might be required to do this step to use certain bundlers;
the third step is to bundle your project code and dependency code into one
or more output files which you would include on your web page as a script.
Then finally you would run your code depending on the setup you might have to run a web server
instead of accessing a static file like you might be used to. In the rest of this talk I'm only
going to talk about the first step, installing Blockly with npm. The rest of the steps generally
follow afterwards but how you set them up depends on you and your project so I'm not going to
address them. However at the end of the slides I do have some links to resources about those steps.
We use them ourselves for all of the plugins in Blockly Samples so you can also look at those for
an example, and we also have examples of using Blockly with several common tools seen here.
Installing an npm package is easy. From your project directory just run "npm install Blockly"
and the Blockly package will be installed and saved to your projects package.json. In the future
if you run npm install all of your dependencies will be updated. By default npm will update to a
newer minor or patch version but not a new major version. So you'll never be automatically updated
to Blockly version 5 for example without explicitly bumping the version number.
This is important because we will generally only put breaking changes that affect public apis
into a new major version, so if you're not patching Blockly and you're only using public
apis as intended then updating automatically with npm should not break your project.
After installing Blockly you can import the default Blockly modules into your code like this.
You'll get the default modules, Blockly core, the built-in blocks, the javascript code generator,
and english language files. Then you can refer to the Blockly scope from within your code like
you're used to. If you need other options such as other language files or other code generators,
you'd have to import the relevant modules. In this example
we're importing the python code generator and the French language.
All of our plugins are available on npm as well. You can search @blockly on npm to find all of the
plugins that we publish. The plugin README will tell you how to install the plugin and
use it from within your code so just follow the directions for the plugin you're using.
There is another alternative to using npm. If you don't want to clone Blockly locally
but you also don't want to set up npm and all the other steps needed,
you can use unpackage. unpackage provides the same code as the Blockly npm package.
You include the script on your page and you can use Blockly from your code like normal.
However by doing this you have no version control whatsoever: you'll always get the latest stable
version of Blockly. For this reason this method is best for quick demos or proof of concepts.
Finally here are some resources to help you learn more about the tools I've talked about.
You don't have to use npm and webpack but those are very common and they're what we use
in Blockly so it's what I focused on. There are alternatives like yarn, browserify,
and others. Last year's summit contained more technical details about what's provided in the
Blockly package if you're already familiar with npm, so if you want more information about what
exactly we publish you should check out last year's talk by Sam. Thank you for listening!