Express app.locals Property

Beginner
⏱️ 9 min read
📚 Updated: May 2026
🎯 4 Code Examples
Express.js

What you’ll learn

  • How to store global template variables with app.locals.
  • How app.locals differs from request-scoped res.locals.
  • How to use shared values in EJS and other view engines.
  • How to avoid unsafe or confusing global-local usage patterns.

Overview

app.locals provides application-wide values available to all rendered views, making shared UI data easy to reuse.

Global template data

Useful for values like site name, brand text, or footer metadata.

View engine friendly

Works with EJS, Pug, and other renderers through res.render().

Shared state caution

Updates affect all requests, so avoid storing request-specific data.

Syntax

javascript
app.locals.key = value
app.locals['key'] = value
  • Assign properties directly on app.locals.
  • Values become available in every rendered template.
  • Use res.locals for request-specific values instead.
1

Basic app.locals setup

javascript
const express = require('express');
const app = express();

app.locals.siteName = 'CodeToFun';
app.locals.year = new Date().getFullYear();

app.get('/', function (req, res) {
  res.render('home'); // home.ejs can use siteName and year
});
2

app.locals vs res.locals

javascript
app.locals.brand = 'CodeToFun';

app.get('/profile', function (req, res) {
  res.locals.username = 'Asha'; // request-only
  res.render('profile');
});

📋 app.locals vs configuration constants

OptionBest forScope
app.localsShared template valuesAll rendered views
Module constants/envBackend logic and secretsServer code only

🧪 Testing checklist

  • Set a value in app.locals and verify it appears in multiple templates.
  • Set a value in res.locals and verify it appears only for that request.
  • Update a global local value and verify subsequent renders reflect the change.
  • Ensure sensitive backend values are not exposed in views.

Pitfalls to avoid

Using for request data

Cross-request leakage risk

Keep per-request user data in res.locals, not app.locals.

Storing secrets

Accidental exposure

Never expose private keys or credentials via template locals.

Uncontrolled mutations

Inconsistent UI output

Treat global locals as shared state and update them intentionally.

❓ FAQ

app.locals is an object for storing application-wide local variables that are available in all rendered views.
app.locals is global for the app lifecycle, while res.locals is request-specific and only available for a single response cycle.
Yes. You can change values at runtime, but changes affect all subsequent requests and rendered views.
No. Avoid placing secrets or private tokens in view-accessible locals.
Use it for shared UI metadata such as site name, footer text, or global helper values needed in templates.

Summary

  • Purpose: app.locals stores app-wide values for rendered templates.
  • Scope: values persist across requests, unlike res.locals.
  • Practice: use for shared UI metadata, not per-user or sensitive data.
Did you know?

app.locals stores values available to all rendered views for the lifetime of the app process.

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

4 people found this page helpful

Express app.listen() Method Express app.engine() Method