Juri Strumpflohner - Create and publish Angular libs like a Pro

all right thank you good so last talk before the coffee break right so but I don't go over time well let's jump straight into my talk so as you can probably guess from my title we are going a bit deep today into building anger libraries and I would like to start straightaway with the question why so why do we actually want to build libraries I think it's from some point quite obvious in the sense that if you built an angular application today normally it's being like you have your own JavaScript files you have few components and stuff but you also have a lot of external libraries and they're kind of the building blocks for your application like you assemble them together and you build something bigger out of it and so for instance if you search for something like a fancy drop-down list or select box like this one then right now chances are quite high if you search them up on Google that you come across this kind of guy right I don't know how many of you know that they have still a lot of plugins and widgets around and they have also widgets built by the community mainly so that's really nice properly which we actually also would like to have for Angra right Frank Ricci went and onwards and so we don't however just want to optimize for the quantity of course but we also want to have a healthy ecosystem so good libraries which are of good quality right great so Who am I I'm us Dom flora I'm a Google developer expert in web technologies specifically in angular I'm coming from South roll Italy so it's in the middle of the Alps and I'm currently working at the company they're called our fridges we are in the spatial data system so where we do web technologies with geographic information systems I'm also an academic structure and freelance trainer and consultant if you want to join me online these are the kind of places where I'm around so it would be cool to see some of you also on there cool so let's get back we were talking about quality right so what does it actually mean to build a good quality library and so Minko wrote a blog post about a year ago more or less and he said a good angle library should have these kind of properties so it should be platform independent which really means like you'll be able to run in webworkers or on the other side as we have just seen before on universal it should be properly bundled and also distributed so it can be built in and get into your application any child should of course work with a OT like that's that kind of the thing you want to do when you go into production right like many of you probably still use git in development mode but that's gonna change now with the latest versions of angular as well with Tanger syl.i and so that's going to be the default and finally it should play while with typescript because type should is like the first-class citizen now in angular and it has a lot of advantages and when I bring in an external library I obviously want to get out completion and compile time check for that library as well but that's actually not enough okay we've just seen in the talks before there are a lot of toolings in the angular system in anger ecosystem so therefore our library might be bootstrapped actually by these kind of different tools there might be booster buy systems yes it might be bootstrap or server side by nodejs as we have just seen and talked before it's for almost a common case now that it's being boosted by web pack or someone might Jim simply take your library and just kick it in as a script tag and your browser so it should work also as a und format and so therefore a library should be basically open to be statically analyzable so that means basically tools should be able to read the source code of our library to understand it and then to apply optimizations such as tree shaking or that code elimination and these are really important because we want to downsize the bundle okay and if you were interested in that kind of stuff I highly recommend to check out the talk by Igor which he gave at reactive conf this year and where he really goes into those details so how to optimize an application for the times interactive and it's really an interesting talk so shipping a library like death is something you also see but it might not be the best we can do so at least not in our kind of scenarios so let's have a look so what does it mean to have a nicely structured library luckily we have something that's called the angular package format and it's right now in version 5 and it's available as a Google Doc online so you can just search it up on Google it's publicly it's open so you can go through it and it's jacket is actually some kind of yeah a set of guidelines and best practices which the angular team itself develops and uses for distributing basically the angular core packages and so therefore if you apply those same principles on your own library you're basically quite safe so meaning your library will want to integrate in the whole angular ecosystem so those various kind of tools which run their grades and so one of the goals here is basically of the package format to support the tools would you just have seen but also to optimize for the bundle size and for the build time and especially the latter one is really important because it's often not that much given attention to but if you think about if it if your application really grows and gets larger and you build time increases that really drains the developer productivity so it should also be something that we should take a look at okay one heart requirement all ESM okay we are now have two equina script modules they're really nice to use so we would like to have his files life there where we have import statements and export statements because that's one of the prerequisites for having that capability of being able to statically analyze your code and to optimize it okay so what does that mean in practice let's have a look like I have here kind of a small really demo application with the types component inside there and that that's component is actually quite a good candidate for being taken out and distributed as a separate library right now we all have a look now but I'm not as brave as Orion Pascal so what I will do is what I call screenshot driven development because what could possibly go wrong so let's create a dedicated library project I take basically the source code of my types component out of the existing application I create set up a new project and it copied in into the source folder so you can see we have our angular module we have two different kind of components and the HTML file and so on now if you take a look at the package Jason there's actually not that man of much of specific stuff or interesting stuff the only thing I would like to you to pay attention to is also the peer dependencies those are basically the kind of requirements the application that consumes your package has to satisfied so if you build something that's only valid from Angra five onwards then obviously you have to specify that here in appear dependencies but of course you would like to keep that as open as possible right so that can be consumed by most people then the next thing is the public api TS file so this is kind of the entry point to our library where we expose everything that should be publicly visible outside and consumable so it's kind of a naming convention or kind of a style guide that you have that public API file and from there everything starts and as you can see it basically takes in a file from the source folder so if we jump there we see I have here inside the source folder an author file which is called here tabs TS and which then again exports all of the files which are inside that source for so that way you can eyes the structure also if you have different kind of modules in there so before Smee before we jump right into the compilation step we have to do some preparation steps before and that's mainly for inlining assets so if you take a look and my library here I followed basically the style guide so I have a HTML file and CSS file as external files especially if they get huge it's quite comfortable to have that and I basically reference them by the template URL and styles URL in my component right but that's not quite ideal like it's good when you develop but it's not so it ideal when you distribute the package afterwards so what we want to have actually is to inline it inside the package and right now there isn't really a standard on how you should do that so what I did for instance is I created a simple script file here inline assets and they kicked in a bunch of tools in this case inline ng to template which is quite handy i specify here resource and destination directory like the destination directory is kind of important because I basically move all of the files when you are processed into a temporary directory and that will be my working directory basically where we do the compilation stuff in this kind of way I avoid messing up my source code cool and then basically I pipe it through that inline and you do template and then we will get basically a result afterwards out of that compilation step so for convenience reasons of course I specify here script and scripts section of my package JSON so built-in line I also copy over the T as far as you can see so I do our nursing before but more more important part is that just below just afterwards the basically invocation of the note inland assets right so if you execute that now what we get is basically a time directory with all of the source files in there and you can now also see that basically that script inline all of the templates there it also was too intelligent to use now the template properly and no more template your routes properly and so we have everything nicely prepared cool so we talked about tools and right now those tools would you would like to support or more or less these kind of tools so those are specified by that angular package format and you can see at the very top which we are going to start with is web pack optimized meaning it reads the equal script 2015 code so it has been augmented with some kind of plugins and closure compiler which is going to be more and more important also in the future and what they require is basically what they want to consume in order to run in the most optimal way if ESM and to es 2015 so ACMA script module with xscape 2015 code so let's have a look let's compile to USM 2015 now when we do as a first step is we create such a TS config file it's not the one which we use for types right it's one dedicated for just during that build process and if you have a look here we have our entry file okay then the one I mentioned before so that would be the entry point for the compilation and then the tools will follow along that entry file and all the import statements and know how many files have to be bundled into the library then above near they are just the normal type script configurations like here we obviously want to generate declaration files because we said we want to support typescript also in our library so with that we generated the creation files then for the module we said we always consume active script 2015 modules and the target will be equal scape 2015 so in this case means we just compiling away the types and finally we have here two out dere and the root directory so as I said the working directory is the temp folder and out there will be the ESM 2015 folder and that as well is something the package format specifies so in the ideal case those kind of source files should finish up in a folder called ESM 2015 alright then you might wonder about this section here below so this kind of an extension because we're not going to use the typescript compiler directly but we are going to use ng c and then GC is basically the angular compiler which wraps the types of compiler so we don't have to execute both of them but ng C will also execute TS c and NGC will basically listen to these kind of settings below here so it's an extension of the type configuration here for instance here it will generate annotations for that closure compiler which we want to optimize for so we will convert types of annotations to closure compatible annotations and we also see here some kind of settings like skip template code generation so that's for the aut mode but actually we don't want to do the 8e compile compilation right in our library but that's something the application with a met our library should do for us we just want to be compatible with that compilation right cool and then it generates that metadata file and that metadata file is actually the one that is being used by LG okay so again we add here a script tag in our scripts section built ESM style 15 as you can see I use the ng C compiler and I pass in a configuration file and if I execute that we get here in a temp folder the source files and as you can see we have here basically the import statements and everything so it's still basically echo script 2015 modules and below we have ActionScript 2015 code because we have the class statement syntax for statements and stuff like that and also further down you can see how it generated also the annotations for the closure compiler now in this case I actually wasn't so so good in developing that part because it actually did not specify type script types on there but otherwise they would have been converted and finally to meet the data file and that's that's what will be consumed by the T compiler to understand how our application is structured okay so so far we're good now we have quite a lot of files like to say in this example it's obviously a dummy example it's like small files that are not so many but actually it can grow quite a lot and what happens there is that Nolan lost and wrote a blog post about a year ago more than a year ago about the cost of small modules so he did basically some kind of an the blog was really huge but it's highly recommended to read that where he found out that small motives are really good for development because you want to separate out in different kind of files but for distribution it's not right not that ideal because there's actually a cost behind of following up all those files and getting them together so that's why the angular team coined the term which is called phezzan and it's nothing else than flat actress script modules so what they want to do is to aggregate everything together in one file and basically to serve that to the public okay so how do we compile actually to fathom 2015 so before we did ESM 2015 now phezzan 2015 well it turns out that roll up is actually quite a good candidate for that so in order to do that with roll-up we can't create such a configuration file and it's quite simple actually I have it is a normal JavaScript file you have an entry component and an entry file and the destination file the entry file comes from that ESM 2015 folder we just did in a previous compilation step so we can read that from that you can see that I reference here in njx top sleep demo so that's that's my entry for which we haven't seen actually before if you didn't pay attention maybe but if you look in the angular compiler options section it is already prepared for generating those flat modules structure and if we have a dedicated property here where you can specify flat module out file and that should be called like this and also flat module ID for instance they worry it is the name how you can then import it in your modules okay in this case njx tab lips demo ok and then we have to specify the format which will be actual script in this case of course and we can again add a script tag now we invoke roll-up we pass it in the configuration and if you execute that now in the dist folder we will get our final directory structure we have any sm start 15 folder and we have now the file in there ok and you can see at the very top the whole import statements have been aggregated together so roll-up is that kind of intelligent to also aggregate them together when they come from the same package and below if cedar is still the actual script 2015 code so we still have classes and those kinds of properties we want to have great check so we now support web pack and Google closure compiler let's see how what we have to do to support also the CLI roll up in web pack and they require ESM but es5 code not es6 code so let's see how to compile dsm-5 and turns out that's actually much simpler because now we have the tools already in place so I use here it extends property from typescript configuration files which is really neat because we can use that previous TS config es2015 file and import it so we get all of those properties and we just overwrite those which we actually want to modify and in this case it's basically in the compiler options of course we change the target we now set it to yes yes 5 and also the output directory is obviously different because now we set it to es m5 and actually that's also something the package format specifies great so we kick in again and you built tasks and before we jump ahead we simply also want to do immediately the thousand compilation so it's like the same thing we did before but now for the new structure with es5 code again obviously roll-up so we can simply here copy the script over then real case scenario you would probably just parameterize it so to optimize a bit out but it's much simpler to fall in his way so i simply copied it I changed the entry file so in this case it points to es m5 the new output basically and then the distractor will be DSM es and 5 again format remains unchanged again we add a script tag now let's first execute the sm5 completion treat before so we get at es m5 directory with all the files in it and now let's execute the phasma compilation and now we get the final destination file in that this folder up there and it looks quite similar to the one before but now we have basically s5 code right you see the VAR statement there there are no more classes which come from es6 ok so second check we're nearly done last step clunker script tags jsfiddle or also no GS okay and they usually consume UMD modules so how we can we create that again roll-up turns out to be quite nice for that as well so we just we can just take the es m5 module we created before ok because they are already is five code so we can take those in and we specifies the directory the bundles folder so the package format says the bundles like human D should finish up in in that kind of folder we have to give it a name because UMD files are basically finishing in the global scope so they have also had to take a name obviously the format will now be UMD right and we have to also specify some kind of Global's which are those for angular basically how they would be exposed in a uniform cool so let's add that UMD tasks there we also want to minify it of course so we want to deploy it they're like extracted but if someone takes it as a script tag in your browser you should have two minified format right so for that I defy is really really nice to use that as you can see here I basically use the dist bundles which we created before from that unique step above and then I gave it a new output directory a new output file which in this case is with the mini suffix so that will be the compressed one great so we run again the UMD build now now we run also the build of the minified part and we get that balance directory at the very top where we have now too far so first extracted one and then the compiled one everything in one line and compress down all right so we support now all of the all of the three tools this is also nicely prepared already but we are missing here some files actually like the typescript definition files which we created earlier okay I mean they are still in a temp directory also here in the source folder so I'm simply adding here a final script which moves those typescript definition files up to that so this directory and then obviously for convenience reasons I group them all together like I have one build command which is usually the usual entry point when you compile a library and it will execute basically those steps we have just seen now separately alright so we can run that build command and now we get basically the final outcome of our library so you can see there is also the package JSON files and we have those entry files actually DG as files and also the the typescript definition files inside there but you might wonder now okay but if I import and the module afterwards like imports apps module from an JX lip steamer how does no Jess for instance know which file to load or how does the Google closure compiler know which file to load and the reason is we have actually missed something here and it's these kind of properties you have to specify in your package Jason so they define which tool is going to read which which file and you can see it points directly to our bundles directory for instance for nodejs or for the module part for like the CLI or web pack it points to the sm5 part which we have defined here and finally Google closure compiler would consume yes yes 2015 part and we also specify the Taipings here because that's where the language server from typescript will pick up without type definitions great so in theory we are now nicely prepared we could now start and iterated over NPM a simple set would be simply execute npm publish on that this directory and you would be basically fine but we really want to automate right so we want to automate as much as possible we want to out to many versioning and also the deployment so let's see how we can achieve that it there's actually a really nice library out there and it has been around already for years it's called semantic release you can look it up on github and it has a nice CLI as well so you can install it with NPM and this is actually a screenshot from their documentation so you execute the magic release setup and then basically you get ask a couple of questions where you get repository is you get user name and kind of preparation steps which it needs to know you can see now in the last line there there is the dot Travis Yama file which it also sets up for us automatically now if you don't know Travis you can find it on this URL it's kind of a continuous integration server which is used quite a lot especially on open-source projects on github and so what Symantec release did for us is actually to set up that kind of script file here for us so you can see here their different kind of sections where you specify the requirements of your library like which node version and so on and then we have basically the script section where we execute the build step and it already set it up to MPN run build because that's the most common starter you find nowadays and that will now execute our different kind of compilation steps which we I've seen before if I would think once well then after success the command Amanda Symantec release will be invoked as you can see NPM run Symantec release and that's something the package sorry CLI has put inside our package Jason so you can see at the enters that Symantec release command and it has a pre step where it basically goes and determines the next version which should be released so it applies semantic versioning we're different kind of there's each number has basically a meaning like angular that's right now as well and it knows how to determine next version by following up with your comments so one of the requirements here are that you use conventional commit messages like the angular team does and like they did already in angularjs and so based on whether it's a feature so as you can see that feed prefix or a fix or tour and so on or whether you have in your comment of your comment message like breaking change it will know which version number to increase that's really nice property because now what we can do is actually or before that basically I have to also hook into that process because as you can see it executes semantics queries pre-snap it will increase the version number now package jason and then i'm going to copy that packages and over tried this directory again in order to have the new version number published also on NPM after that happens it goes to the NPM publish disk which we mentioned before so it simply picks up our list directory and published it on NPM and then our some post steps which it executes which are basically for uploading to github a change log and doing a release tag there okay so with that we are nearly set up so one thing we have to do obviously in that you have to do that the first time you use Travis you have to set up to github token and your and p.m. token such that when semantic release runs on basically on Travis it is able to actually publish to those those kind of destinations right and so once we commit now we push it up to our github repository Travis will automatically pick that up it will start compiling by following up that Yammer file which we have to find and if you everything went fine at the very end you get a some an NPM run Symantec release which will then basically do those steps we have just seen so it will determine a new version number and I will kick it up on NPM and github and in fact you can see determined here in this case of malaria first version zero one zero it published it automatically on NPM so you will get a new release tag there and it also creates which is really nice and you release inside github and below there is a nice change lock which even references pull requests or your comments which you did did so you have there a features list and a bug fix list if there would be any and that's extremely nice properties especially if you have a public repository on github you can even just review pull requests on your mobile device and with a button click you basically merge it into master and that will kick off that whole automation process and publish it on NPM and on github that's really not so much time cuz it's time-consuming it's really nicely manageable ok so let's do some considerations and wrap up so the question you might ask now is do we really have to do all of this by hand now I've showed you the different kind of steps really step by step in order to know what's going on behind the scenes because I think that's quite important in order to understand how it works and in some cases you might even use that kind of setup because you want to have full control of what is going to happen but actually they are quite some good libraries around there so one is human generator which is actually by your conference organizer which is really nice package library basically which generates in scaffolds you're out the initial structure and you can use that and go on with that for compiling arrival for building your library so you don't have to take care about the whole compilation process and set it up a similar approach is in order packages a package which emerged quite recently which is called ng packager and that ng packages has a kind of a different approach you install it as an NPM package and then you included in your package jason and invoke it buy directly from your build steps and it will then figure out the structure of your library and then start compiling it always following the angular package format so both of them actually follow them of course ok another thing which I'm really looking forward to is angular CLI schematics so if you haven't seen the talk by hands-on angular connect I would definitely recommend you to watch that one angle a schematics are actually a way for extending the CLI and at your custom behavior on it and I think that would be actually a good alternative for automating the kind of library the code production right it's currently still elapsed project but I think we will see that very soon as in production one thing I didn't mention actually from the beginning is actually what should go into your library what should you bundle into your library well it should be and this is a quote from the package an informer document actually it should be the smallest set of logically connected codes you should really just connect put in those code which is somehow tied together and leave everything is out also if you build like UI library where you have type components and buttons and stuff a bit like angular UI material angular material and you should also look up how they do it actually is you should not have one energy module which we export and there you export everything because then you force all of the developers which are probably just interested in radio buttons as Pascal showed us today to take all of the bed load within with them into the library right so you should dear create different kind of energy modules and export them separately and the angular package format has actually specification for that so you should look up the document which I referenced because they have basically primary entry points and secondary entry points and with that kind of where you can manage large libraries where are multiple components cool and we learned about today we have seen how to make our library compatible right how to make you type suit friendly by exporting the typescript definition files we have seen how to optimize the different kind of tooling so for systems yes for nodejs for uni and those kind of things that it works nice in anger ecosystem and finally you are forced to learn what that phasma means because might sounds quite strange if you hear it first time and definitely look up the angular package Foreman finally the whole automation part use semantic versioning also if you export your library it's a good practice to use your own namespace in front of it like angular does it at angular slash and then usually in the community people have agreed to use an NG x- prefix before so one can immediately recognize this is something when it comes from the community rather than from the angular team itself and obviously right for your libraries and automate everything out of it so the source code for that library is online I will tweet my talk out to this light for talk out later so definite out I also created the comments in different kind of steps so you can follow it along quite easily and yeah now you're free go out and create awesome libraries for angular Thanks

Channel: NG - BE

Views: 21,338

Keywords: angular, ngbe, conference, web, libraries, publish, javascript, typescript

Id: K4YMmwxGKjY

Length: 29min 32sec (1772 seconds)

Published: Fri Dec 15 2017