Mimosa is a build tool for Node.js apps. But it's more than just building. For a very nice introduction, check out the 'Tour of Mimosa' slideshow on their homepage.
In short, it will do almost anything you need to get from the source of your web app to something that you can deploy to the server: JS transpiling, CSS linting, JS hinting, minification, dependencies, etc.
But it also helps while developing, for example by allowing live reload so you see the changes you've made in your browser immediately.
Also, there are 'skeletons', which are a sort of project templates. These get you started quickly. And that's what Mimosa is about. Getting up to speed quickly, and not having to add a massive amount of configuration.
I had some trouble getting the Durandal skeleton to work on NodeJS on Microsoft Azure. I don't think my problem was Durandal related, so you might find this helpful for other Mimosa and NodeJS apps on Azure.
To get started, install Node.js. If, like me, you're on Windows, go to nodejs.org, download and run the installer. This will install Node.js, which now means you also have NPM. NPM is the Node Package Manager and allows you to easily install Node packages, either globally for all your Node stuff, or locally for your specific app.
Start the Node.js console and enter
npm install -g mimosa
The -g flag means it will install globally (so you can re-use it in other NodeJS apps).
If, like me, you want to create a Durandal app quickly, just run
mimosa skel:new durandal path/to/your/app
Not every dependency has been installed yet, so you still need to run
This will look at your package.json file and install all dependencies.
and navigate to localhost:3000 in your browser. Presto!
And now comes the trouble: getting this to work in Microsoft Azure. I had set up Azure to pull in my GitHub repository and host it. That's actually very simple from the Azure management portal. However, I was getting an internal server error.
What's important to realize (and something I forgot) is that Azure is actually just pulling in the source of our app. Mimosa helps us in our development, but we still need to build everything. The documentation on Heroku and Jay Harris helped out a bit here.
In our mimosa-config file, we need to have the web-package as dependency and in our .gitignore file, we should have the /dist directory in comment (so it is checked in). If you used the Durandal skeleton like I did, this is already done. Web-package is responsible for packaging everything up. And the /dist folder is where the results of all the linting, minification, packaging, etc is placed. This is the folder that we want in Azure.
First, we need to build everything:
mimosa build -omp
The flags mean it wil optimize, minify and package our code. It's the packaging that's important. You should now have a /dist folder in the root of your project. Inside, there's all sorts of files, including app.js.
Now we want Azure to run this app.js file in our /dist directory. On Azure, there is a component called Kudu that is responsible for syncing with GitHub. It essentially just pulls in the contents of the repository and tries to host what it found. But we need to help it a little, because we've used Mimosa, and our stuff is in the /dist folder.
First, install the Azure Command Line tools if you haven't already. You can do this via NPM:
npm install azure-cli -g
Next, generate the default Kudu scripts:
azure site deploymentscript --node
This will add a .deployment and a deploy.cmd file. Have a look at both, but the interesting one is the deploy.cmd file. Scroll down to the deployment section. You will see that it does the following:
- Kudu sync (pull in the changes from GitHub)
- select node version
- install node packages
In the first part, change "%DEPLOYMENT_SOURCE%" to "%DEPLOYMENT_SOURCE%/dist". Now, Kudu will not sync the entire repository, but only the dist folder. This means only our packaged, minified, linted,... code will be deployed.
Build everything again (with mimosa build -omp) so our deployment scripts for Kudu are in our /dist folder. Now add everything to your repository (if you haven't already). It is possible that you'll get an error because certain paths are too long for Git. You can avoid this by adding dist/node_modules to your .gitignore file. Because we're going to install the necessary node packages on the server via the deploy.cmd anyway, we don't actually need the contents of this folder.
Setting up an Azure website to pull in a Git repository is beyond the scope of this post. But after pushing all your commits, you should see the latest commit in the deployment tab of your website. However, surfing to your new URL will give you an error. The reason for this is that Azure will look for server.js as entry point to your NodeJS app, but Mimosa starts in app.js.
We can change this in the web.config file that Azure has generated for us. In the dashboard tab of you website, connect to the FTP address you see there (you may have to set up credentials) and download the web.config to the root of your repository. Open it up and change all references of server.js to app.js. Commit, build (mimosa build -omp), push and your Durandal skeleton for Mimosa should be up and running on Microsoft Azure!
Possible next steps could be to make a bat file that does the mimosa build, commit and push; or make Azure do this for you. This may be a long post, but when you follow the steps provided, this isn't actually a lot of work (it was to find though!). Check out the commit log of my GitHub repository to see the necessary steps.