visualforce-template-webpack-plugin

Webpack plugin that simplifies the updating of Visualforce files to serve your webpack bundles

Usage no npm install needed!

<script type="module">
  import visualforceTemplateWebpackPlugin from 'https://cdn.skypack.dev/visualforce-template-webpack-plugin';
</script>

README

Latest Stable Version NPM Downloads License

Visualforce Template Webpack Plugin

This is a Webpack plugin that simplifies the updating of your Visualforce pages by automatically including your static resource file(s) references as script and link tags. More about referencing static resource files in Visualforce markup here.

Install

npm i visualforce-template-webpack-plugin --save-dev

Read Before Moving On!

  • Do not put anything between <!--% scripts %--><!--% scripts %--> comment tags. They will be erased!!

Configuration

Step 1: Import/Require Plugin into Webpack config file

webpack.config.js

const VisualforcePlugin = require('visualforce-template-webpack-plugin')

Step 2: Visualforce Template Declaration

In your Visualforce Page, you need to declare where you want the assets to generate.

% scripts % for your js files and % styles % for your css files

Spacing does not matter

<!--%scripts%-->, <!--% scripts %-->, or <!-- % scripts % -->

App.page

<apex:page>
    <head>
        <!--% styles %-->
        <!-- WARNING: Do NOT Put anything [HERE]. Will get erased -->
        <!--% styles %-->
    </head>
    <body>
        <apex:form>
            ...
        </apex:form>
        <script>
            //put non webpack/global javascript here
        </script>
        <!--% scripts %-->
        <!-- WARNING: Do NOT Put anything [HERE]. Will get erased -->
        <!--% scripts %-->
    </body>
</apex:page>

Step 3: Add a new instance of the Imported/Required Plugin configuration

webpack.config.js

//From Step 1
const VisualforcePlugin = require('visualforce-template-webpack-plugin')

module.exports = {
    entry: './index.js',
    output: {
        filname: '[name].bundle.js',
        path: "./force-app/main/default/staticresources/dist"
    },
    plugins: [
        // Add a new instance here
        new VisualforcePlugin({
            page: './force-app/default/main/pages/App.page'
        })
    ]
}

Options

Plugin accepts {Object} or {Array} of objects w/ the following data structure

Name Type Default Required Description
entry {String} or {Array} of strings main false Name of entry configuration key name. Needs to match your webpack config entry names. Defaults to all entrypoint assets if none specified.
page {String} undefined true Relative path to your visualforce page or component file
scriptHook {Function} undefined false Callback function to modify src and other attributes on script tag
styleHook {Function} undefined false Function to hook into modifying attributes of link tags

Additional Option Info

You can filter out entrypoint assets you wish to not include in the page.

webpack.config.js

modules.exports = {
    entry: {
        app: './app.js',
        main: './main.js',
        mobile: './mobile.js'
    },
    output: {
        filename: '[name].bundle.js',
        path: path.resolve(__dirname, "force-app/main/default/staticresources/dist"),
    },
    plugins: [
        new VisualforceTemplate({
            entry: ['app', 'main'],  // mobile entry is not included
            page: path.resolve(__dirname, 'force-app/main/default/pages/App.page')
        })
    ]
}

Script Function Hooks Details

Script Tag Attribute Defaults

Name Default
type text/javascript
src [Depends on output in static resource]
async false
defer false
nomodule false

Example: <script type="text/javascript" src="[]" />

How to overide defaults: Return an Object and setting any of the properties in the table above. Only need to include the script tag attributes you wish to change. The function is passed an object containing:

scriptHook: (scriptData) => {
    const { resourceName, resourceFilePath } = scriptData;
    // ...
    return { 
        src: `${resourceName}/${resourceFilePath}`
    } 
}

examples of using the options

new VisualforcePlugin({
        entry: 'app',
        page: path.resolve(__dirname, "./force-app/default/main/pages/App.page"),
        scriptHook: ({ resourceName, resourceFilePath }) => {
            // ...
            return {
                src: `{!URLFOR($Resource.${resourceName}, '${resourceFilePath}')}`,
                type: 'text/javascript'
            }
        }
    })

new VisualforcePlugin({
        entry: 'app',
        page: path.resolve(__dirname, "./force-app/default/main/pages/App.page"),
        styleHook: ({ resourceName, resourceFilePath }) => {
            return {
                rel: 'stylesheet',
                href: ``,
                type: ''
            };
        }
})

Example(s)

webpack.config.js

const path = require('path')
const VisualforcePlugin = require('visualforce-template-webpack-plugin')

module.exports = {
    entry: {
        app: './index.js'
    },
    output: {
        filename: 'bundle.js'
        path: path.resolve(__dirname, "./force-app/main/default/staticresources/dist")
    },
    plugins: [
        new VisualforcePlugin({
            entry: 'app',
            page: './force-app/default/main/pages/App.page'
        })
    ]
}

Before:

App.page

<apex:page>
    <apex:pageBlock>
    ...
    </apex:pageBlock>
    ...
    <!--% scripts %-->
    <!--% scripts %-->
</apex:page>

After:

App.page

<apex:page>
    <apex:pageBlock>
    ...
    </apex:pageBlock>
    ...
    <!--% scripts %-->
    <script type="text/javascript" src="{!$Resource.dist, 'bundle.js')}"></script>
    <!--% scripts %-->
</apex:page>

Bundle Splitting

if your entry point has code/bundle splitting then your page might result in

<apex:page>
    <apex:pageBlock>
    </apex:pageBlock>
    ...
    <!--% scripts %-->
    <script type="text/javascript" src="{!$Resource.dist, 'polyfill.js')}"></script>
    <script type="text/javascript" src="{!$Resource.dist, 'vendor.js')}"></script>
    <script type="text/javascript" src="{!$Resource.dist, 'bundle.js')}"></script>
    <!--% scripts %-->
</apex:page>

Updating Multiple Visualforce File(s)

example of updating more than one visualforce page w/ multiple entries

webpack.config.js

const path = require('path')
const VisualforcePlugin = require('visualforce-template-webpack-plugin')

module.exports = {
    entry: {
        app: './app.js',
        admin: '/admin.js',
        mobile: './admin.js'
    },
    output: {
        filename: '[name].bundle.js',
        path: path.resolve(__dirname, "./force-app/main/default/staticresources/dist")
    },
    plugins: [
        new VisualforcePlugin([{   
                entry: 'app',
                page: path.resolve(__dirname, "./force-app/main/default/pages/App.page") 
            },
            {
                entry: 'admin',
                page: path.resolve(__dirname, "./force-app/main/default/pages/Admin.page")
            },
            {
                entry: 'mobile',
                page: path.resolve(__dirname, "./force-app/main/default/pages/AppSf1.page")
        }])
    ]
}

Outputting File(s) directly nested w/ in force-app/main/default/staticresources/ directory. (Not recommended)

If your output combination of your path and filename is only one level deep w/ in staticresources then your file name(s) need to change from any characters such as . to underscrores _ since salesforce doesn't allow non alphanumeric characters in the file name

W/ this config change the following

output: {
    filename: '[name].bundle.js'
    path: path.resolve(__dirname, "force-app/main/default/staticresources/")
}

to

output: {
    filename: '[name]_bundle.js'
    path: path.resolve(__dirname, "force-app/main/default/staticresources/")
}

or

output: {
    filename: '[name]_bundle.resource'
    path: path.resolve(__dirname, "force-app/main/default/staticresources/")
}

If your splitting chunks as well you'll want to do the following in your optimization

optimization: {
    splitChunks: {
        chunks: 'all',
        entry: (module, chunks, cacheGroupKey) => {
                const moduleFileName = module.identifier().split('/').reduceRight(item => item);
                const allChunksNames = chunks.map((item) => item.name).join('_');
                return `${cacheGroupKey}_${moduleFileName.split('.')[0]}`.split('-').join(''); 
        }
    }
}

for example if your using react, react-dom split bundle might result in vendors_reactdom_bundle.js;

Ngrok/Development Hook Example

Handy if you want to implement a dev config w/ live updating w/ out refreshing the visualforce page

new VisualForceTemplatePlugin({
    entry: 'main',
    page: './force-app/main/default/pages/App.page',
    scriptHook: (scriptData) => {
        const { resourceName, resourceFilePath } = scriptData;
        return {
            src: `https://mjyocca.ngrok.io/${resourceName}/${resourceFilePath}`,
        }
    }
))

Output App.page

<!--% scripts %-->
<script type="text/javascript" src="https://mjyocca.ngrok.io/vendors_admin~main_react_dom/vendors_admin~main_react_dom.bundle.js"></script>
<script type="text/javascript" src="https://mjyocca.ngrok.io/main/main.bundle.js"></script>
<!--% scripts %-->

vs

<!--% scripts %-->
<script type="text/javascript" src="{!URLFOR($Resource.vendors_admin~main_react_dom, 'vendors_admin~main_react_dom.bundle.js')}" ></script>
<script type="text/javascript" src="{!URLFOR($Resource.main, 'main.bundle.js')}"></script>
<!--% scripts %-->