I have just released version 3.1 of SPClientSideDeployment with added support for minified JS/CSS. You are now able to include minified files in the deployment package that the tool generates, and instruct the generated PowerShell script to use them during deployment.
Download it now!
You can download the latest version of SPClientSideDeployment from the Visual Studio Gallery.
The challenge with minified files
A typical challenge when using minified files is that you’d only want to use them in production. In dev/test you typically want to continue using the unminified version for debugging purposes. The challenge is to have a mechanism that enables you to switch to using the minified version for production without having to change the source code of the consuming pages.
Seamless dev-prod transition with SPClientSideDeployment
SPClientSideDeployment addresses this challenge by enabling you to include both minified and unminified versions in the deployment package that it generates, and then specifying which version to use when executing the PowerShell deployment script (also generated by the tool – check out this post if you are not familiar with the package generation feature of SPClientSideDeployment).
Your consuming pages will always reference the same JS/CSS file names – e.g. script.js. The content of script.js will be minified or unminified depending on the parameter you provide when executing the deployment script. SPClientSideDeployment’s Visual Studio command continues to deploy the unminified version. This allows you to continue debugging while in development, and then seamlessly transition to minified versions when the solution is promoted to higher environments.
Walkthrough
OK, let’s have a look at an example scenario.
Let say you have a page layout, ContentPageLayout.aspx, and that page references a stylesheet, styles.css. In Visual Studio you use LESS for the stylesheet. Your DeploymentSettings.xml file may appear as follow:
<DeploymentSettings>
<Files>
<File localPath="styles.less">
<Destinations>
<Destination targetFolder="Style Library"/>
</Destinations>
</File>
<File localPath="ContentPageLayout.aspx">
<Destinations>
<Destination targetFolder="_catalogs/masterpage"/>
</Destinations>
<Metadata>
<!-- Metadata required for the page layout omitted -->
</Metadata>
</File>
</Files>
</DeploymentSettings>
You have installed the Web Compiler extension, and therefore styles.css and styles.min.css are automatically generated for you each time styles.less is changed.
During development you use various methods supported by SPClientSideDeployment, e.g. auto-deploy on save, to deploy the compiled output of styles.less to SharePoint. This will always deploy the unminified version, styles.css, to SharePoint.
Publish the package and include minified files
Now you are ready to promote the solution to a higher environment. Right-click the project in the Solution Explorer and choose SharePoint \ Publish Deployment Package. The dialog below appears after you have selected a publish location.
Tick the “Include minified files if available” option and click OK. This option creates a “__minified” sub-folder under the selected publish location and copies the minified version of all files referenced in DeploymentSettings.xml to this sub-folder (if they are found). The unminified versions are always included in the package.
If you had selected F:\Test as the publish location, the published package would contain the following:
- F:\Test\ContentPageLayout.aspx
- F:\Test\styles.css
- F:\Test\__minified\styles.min.css
- [other files omitted]
Execute the deployment script and specify to use minified files
The published package includes a generated PowerShell file, namely DeployFiles.ps1. To execute the deployment using the minified files, include the -UseMinifiedFiles switch parameter. For example:
.\DeployFiles.ps1 -DeploymentSettingsFilePath .\DeploymentSettings.xml -SiteUrl http://myServer -AuthenticationMethod Windows -UseMinifiedFiles
Check this post for other parameters that can be specified.
When the script encounters style.less in the DeploymentSettings.xml, it will take the file F:\Test\__minified\styles.min.css and upload that to SharePoint as styles.css. If the -UseMinifiedFiles switch was not specified, the script would use the file F:\Test\styles.css instead. Since in either case the target file name will be the same, styles.css, no source code changes to the consuming page are required.
Does SPClientSideDeployment perform the minification?
No. The tool is only responsible for including the minified files in the package that it generates and allowing you to use them as part of the deployment. You must use other tools to perform the minification. You can use the Web Compiler extension to do this for example if you are working with JSX, LESS or SASS.
How does SPClientSideDeployment locate the minified files?
When the tool encounters a ‘minifiable’ file, i.e. with .js or .css extension, it looks for the minified version in the same physical location as the unminified version. The file name of the minified version must correspond to that of the unminified version, e.g. scripts.min.js for scripts.js, styles.min.css for styles.css.
What about ‘compilable’ files such as JSX, LESS or SASS?
SPClientSideDeployment supports JSX, LESS and SASS – and this includes minified compiled output. When a compilable item is encountered in the DeploymentSettings.xml, e.g. form.jsx, the tool first looks for the associated compiled output, which in this case would be form.js. The tool then look for a minified version of this output, i.e. form.min.js. Both form.js and form.min.js would then be included in the generated package and processed in the same manner as other minifiable files.
What if my solution uses a mixture of minified and unminified files?
When publishing the package, the tool simply ignores any minified file that it could not find.
When executing the deployment, if the -UseMinifiedFiles switch is specified but a minified version is not available for a minifiable file, then the tool will fallback to using the unminified version for that particular file. A warning will be generated in this case.
What if my solution uses a minified library such as jquery?
If your DeploymentSettings.xml file references minified libraries, such as jquery_1.10.2.min.js, then these are treated as ‘non-minifiable’ and they will be processed in the same way as other non-JS/CSS files. This means the tool will not look for a minified version.
In my DeploymentSetttings.xml file, do I need to explicitly reference each minifiable file?
No. You can explicitly reference the minifiable file using the File element, or use folder-based declaration using the Folder element. When processing a referenced folder, the tool will look for minified version of any minifiable file within that folder and its sub-folders.
Conclusion
This release of SPClientSideDeployment aims to streamline your process in developing with minifiable files and transitioning from dev to production. I hope you find it useful – and as always, would love to hear from you with feedback and suggestion.
