npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

commonjs-soy

v0.0.2

Published

Compile Soy/Closure Templates and convert to CommonJS modules.

Downloads

4

Readme

Build Status codecov #commonjs-soy commonjs-soy is a tool for compiling Soy/Closure Templates and converting them to CommonJs modules.

This is done by using the latest SoyToJsSrcCompiler.jar (from the closure-templates package) to compile your templates and then parsing the resulting js (using Esprima) and removing and/or replacing calls to goog.(require|provide|module|DEBUG).

Features

  • Current implementation uses node-java to call SoyToJsSrcCompiler so no temporary directories/files are needed!
  • Additionally, when combined with a build tool like Grunt or Gulp, the compiler stays in memory so build times are lightning fast (as opposed to tools that spin up a new instance of the jar each time).
  • {call ...}s to external templates are converted to requires (e.g., {call my.other.template data="all"/} => require('./my/other').template(opt_data)) ... super helpful for static analysis and/or browserify-ing.

Installation

npm install commonjs-soy --save

Usage

Requiring:

var soy = require('commonjs-soy');

Api:

.compileSoy(soy[, opts], callback)

Compiles a Soy template and returns as JavaScript source (same as running java -jar SoyToJsSrcCompiler.jar ...).

soy should be a string/Buffer of a raw, uncompiled Soy template.

opts is an optional object where you can define opts.path to be used as a reference in error messaging (NOTE: nothing is loaded from disk using this property).

callback(err, js) should be a function which accepts two parameters, err and js. err will exist if there was an error during compilation (usually, directly from SoyToJsSrcCompiler.jar). js will be the compiled Soy template as a string.

var fs = require('fs');
soy.compileSoy(fs.readFileSync('template.soy'), {
  path: 'template.soy' // this doesn't actually load the template from this path... it' just used as a reference in error messages
}, function(err, js) {
  if (err) throw err;
  fs.writeFileSync('template.soy.js', js);
});

.transformToCommonJs(contents[, modulePathResolver], callback)

Transform contents (which is the js source of a compiled Soy template -- presumably the output of compileSoy) to be a CommonJs module.

modulePathResolver(path, moduleId) should be used to return a valid path that can be used in the generated require statement. For example, you might return a path that's relative to the final output directory (instead of the current directory). path is the value after converting the namespace to a filesystem path (using the convention of periods are equal to slashes). moduleId is the original, unconverted value.

callback(err, js) is called after all transforms have been done. err is an Error object and js is a string with references to goog.(provide|module|require|DEBUG) either replaced or removed to be CommonJs compatible.

var fs = require('fs');
var template = '...'; // compiled soy template
soy.transformToCommonJs(template, function(path, moduleId) {
  return './public/js/templates/' + path; // ... this is just an example
}, function(err, js) {
  if (err) throw err;
  fs.writeFileSync('template.soy.js', js);
});

.transpile(opts, callback)

Runs both compileSoy and transformToCommonJs as a single function to transpile a Soy template to a CommonJs module.

opts can be a string (the equivalent to defining opts.content below), or an object with these properties:

  • opts.content should be a string which is the raw source of a Soy template.
  • opts.path should be the path to the passed in template. NOTE: nothing is read from this path, it's simply used as a reference in error messaging.
  • opts.resolver is a function that's passed as the modulePathResolver arg in transformToCommonJs (see documentation above).

callback(err, js) is called after all transforms have been done. err is an Error object if either compileSoy or transformToCommonJs failed and js is a string with references to goog.(provide|module|require|DEBUG) either removed or replaced to be CommonJs compatible.

var fs = require('fs');
soy.transpile({
  content: fs.readFileSync('template.soy'),
  path: '',
  resolver: function(path, moduleId) {
    return './public/js/templates/' + path; // ... this is just an example
  }
}, function(err, js) {
  if (err) throw err;
  fs.writeFileSync('template.soy.js', js);
});

Caveats/TODOs

  • In order to actually export your templates to module.exports the namespace must be set to an underscore, like this: {namespace _}. (Although, this will likely change in the future).
  • While node-java is well tested, it can be difficult to build in some environments and as such, you should be aware of that when using in production. Note: I'm open to moving off of node-java if the right PR comes along ;)
  • Errors (from invalid templates, etc) are not gracefully handled at the moment.
  • Bidi/i18n isn't supported yet.
  • css (via goog.getCssName) isn't supported yet either.