Integrate express.js application and docpad

I've been using docpad to pre-generate a front-end html/js application (using docpad generate --env static). After a few hangups and a bug fix from balupton it now works great and saves me a lot of time. I simply copy these file to an existing apache server for deployment.

I have now also created a node.js/express.js back-end application that uses a simple api to feed data to the client. This code was created and run independently from the docpad/static files generated as I discussed above.

I'd now like to integrate these two. How is this typically done in the docpad world? I see several options:

1) The back-end and front-end code are kept separate. Docpad is used to generate the front-end static files then a separate back-end application is used to serve the static files and data. Only the static files and express app are copied to the server for deployment.

2) The back-end source files are generated along with the front-end files and copied to the server for deployment. I guess this is almost the same as #1 except the src/files directory needs to include the express.js application files and would allow me to run pre-processors on the back-end source.

3) My back-end application requires docpad (which generates the out/ directory and adds docpad middleware) then starts the server (something like shown here: https://github.com/bevry/docpad/issues/342). This would streamline testing but the entire project directory structure (src/, out/, and all) would need to be copied to the server for deployment.

I'm not asking specifics on how to do this but wondering what is considered the docpad philosophy on this. Is there another option I missed?

Thank you.

The question becomes where do I put the server generating javascript (call it app.js)? In the project folder root next to docpad.coffee or in the src/ directory? Then how do I get docpad to use this instead of the built-in server during testing. Thanks for your help

So to do that, you would create app.js that contains something like what the API docs pertain to:

var docpadInstanceConfiguration = {
    env: 'static'
};
require('docpad').createInstance(docpadInstanceConfiguration, function(err,docpadInstance){
    if (err)  return console.log(err.stack);
    var generateOpts = {};
    docpadInstance.action('generate', generateOpts, function(err,result){
        if (err)  return console.log(err.stack);
        // ...
    });
});

You would then update your Procfile (for heroku) and your package.json main entry (for everything else) to point to app.js instead of the detault ./node_modules/.bin/docpad-server

You can also pass over serverHttp and serverExpress to docpad via the docpadInstanceConfiguration if you want to define your own express server that DocPad should use. More info here.