How to Use Custom JavaScript in WeWeb: Workflows, Scripts, and NPM

Custom JavaScript actions live inside WeWeb workflows. To add one: select an element in the editor (e.g., a button) → click the Workflows tab in the right panel → click the trigger you want (e.g., On click) or add a new trigger → click the + icon to add an action → scroll through the action list and select Custom JavaScript. A code editor opens inline. You write standard JavaScript here — no async/await needed for simple operations, but async is fully supported. The action runs when the workflow trigger fires. Each Custom JavaScript action is a discrete step in the workflow sequence — it runs after all previous actions complete and before subsequent ones begin.

Inside a Custom JavaScript action, you can read WeWeb variables using the formula syntax. WeWeb injects context variables automatically. To access a page variable named 'searchQuery' inside a JS action, reference it directly as a workflow variable by binding it: click the Variables icon in the code editor toolbar to insert a variable reference. Alternatively, you can access the window object for truly global state. To update a variable from within JavaScript, use the 'Change variable value' action that follows your JS action — return the new value from your JS action (see next step), then use that returned value in the Change variable step. The preferred pattern is JS action computes → returns result → Change variable action stores it.

1// Workflow Custom JavaScript action
2// Access a variable passed in from the workflow context
3const inputValue = variables['searchQuery']; // bound via workflow variable picker
4
5// Perform computation
6const cleaned = inputValue.trim().toLowerCase();
7const words = cleaned.split(' ').filter(w => w.length > 0);
8const formatted = words.map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
9
10// Return the result for the next workflow step to use
11return { formattedValue: formatted, wordCount: words.length };

The return value from a Custom JavaScript action is one of WeWeb's most powerful features — it allows you to pass computed data to later actions in the same workflow. Return any JavaScript value: a string, number, object, or array. After your JS action, add a 'Change variable value' action. In the value field of the Change variable action, click the plug icon (🔌) to open the formula editor. Select 'Workflow' context → your JS action's return value → the specific key you returned. For example, if your JS action returned { formattedValue: 'Hello' }, you would access it as workflowResults['YourJSActionName'].formattedValue. This pattern keeps your WeWeb variables as the single source of truth while using JS for computation.

1// Async example — fetch external data and return it
2async function fetchUserData() {
3  const response = await fetch('https://api.example.com/user/123', {
4    headers: { 'Authorization': 'Bearer ' + variables['authToken'] }
5  });
6  
7  if (!response.ok) {
8    throw new Error(`HTTP error: ${response.status}`);
9  }
10  
11  const data = await response.json();
12  
13  return {
14    userId: data.id,
15    displayName: data.first_name + ' ' + data.last_name,
16    email: data.email,
17    fetchedAt: new Date().toISOString()
18  };
19}
20
21return await fetchUserData();

When you need to manipulate the DOM from a workflow JS action (e.g., focus an input, scroll to an element, measure dimensions), WeWeb provides the thisInstance API. thisInstance refers to the root DOM element of the component that contains the workflow — scoped to that specific component instance. This is preferred over document.querySelector() for two reasons: it is scoped (will not accidentally match elements in other component instances when the component is repeated), and it is more performant. Use thisInstance.querySelector() to find child elements within the component. For actions like scrollIntoView, getBoundingClientRect, or direct style manipulation, thisInstance is the correct entry point.

1// thisInstance — scoped DOM access (preferred over document.querySelector)
2// Inject point: Workflow Custom JavaScript action
3
4// Scroll to this component instance
5thisInstance.scrollIntoView({ behavior: 'smooth', block: 'center' });
6
7// Focus an input inside this component
8const input = thisInstance.querySelector('input[type="text"]');
9if (input) {
10  input.focus();
11  input.select(); // Select all text in the input
12}
13
14// Get the dimensions of this component
15const rect = thisInstance.getBoundingClientRect();
16return {
17  width: rect.width,
18  height: rect.height,
19  top: rect.top,
20  left: rect.left
21};
22
23// Apply a temporary highlight (use CSS classes instead for persistent styles)
24thisInstance.style.outline = '2px solid #3b82f6';
25setTimeout(() => { thisInstance.style.outline = ''; }, 1500);

For scripts that need to run once on every page load — analytics tags, tracking pixels, third-party chat widgets, or utility libraries — use the project-level code injection. In the editor, click the gear icon in the left navigation bar to open App Settings. Click Custom Code. You will see two text areas: Head (injected before the closing </head> tag) and Body (injected before the closing </body> tag). Head is for critical scripts, stylesheets, and preload hints. Body is for non-critical scripts that should load after the page renders. Paste your script tags here. Important: do NOT include opening or closing <html>, <head>, or <body> tags — only paste the script/style tags themselves. Note that custom code does NOT render in the editor preview — you must publish to see injected scripts active.

1<!-- Inject point: App Settings → Custom Code → Head section -->
2<!-- Google Tag Manager -->
3<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
4new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
5j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
6'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
7})(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
8
9<!-- Intercom chat widget -->
10<script>
11  window.intercomSettings = {
12    api_base: "https://api-iam.intercom.io",
13    app_id: "YOUR_APP_ID"
14  };
15</script>
16<script>(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/YOUR_APP_ID';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};if(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})()</script>

WeWeb's NPM plugin lets you import any npm package into your project, making it available as a global variable you can use in workflow JS actions. To install: navigate to Plugins in the left navigation bar → click Extensions → find NPM packages → click Install. In the NPM plugin settings, add the package you need: enter the package name (e.g., 'lodash', 'dayjs', 'uuid') and the variable name it should be exposed as globally (e.g., '_', 'dayjs', 'uuid'). WeWeb loads the package from a CDN and makes it available globally. In your workflow JS actions, use the global variable name you specified. For example, with lodash installed as '_', you can call _.groupBy(), _.sortBy(), _.cloneDeep() etc. directly in any JS action.

1// Inject point: Workflow Custom JavaScript action
2// Prerequisites: NPM plugin installed with dayjs as 'dayjs' and lodash as '_'
3
4// Using dayjs for date manipulation
5const orders = variables['ordersCollection'];
6
7// Group orders by month using lodash
8const byMonth = _.groupBy(orders, order => {
9  return dayjs(order.created_at).format('YYYY-MM');
10});
11
12// Calculate monthly totals
13const monthlyTotals = Object.entries(byMonth).map(([month, monthOrders]) => ({
14  month,
15  total: _.sumBy(monthOrders, 'amount'),
16  count: monthOrders.length,
17  avgOrder: _.meanBy(monthOrders, 'amount')
18}));
19
20// Sort by month descending
21const sorted = _.orderBy(monthlyTotals, ['month'], ['desc']);
22
23return { monthlyTotals: sorted };

WeWeb provides two ways to compute dynamic values: formula expressions (the binding formula editor, accessible via the plug icon on any property) and Custom JavaScript workflow actions. Choose formula expressions for: binding element properties to dynamic data, filtering collections, conditional visibility logic, text formatting, simple math, and any reactive binding that should update automatically when source data changes. Choose Custom JavaScript actions for: imperative logic that runs in response to a specific event, complex multi-step computations that are too long for a single formula, DOM manipulation, async operations (API calls, file processing), operations that should run only once when triggered (not reactively), and anything requiring error handling with try/catch. Mixing both is normal — formulas for display bindings, JS actions for business logic.