@apostrophecms/seo
Advanced tools
Ensure your content gets found by search engines and AI systems with comprehensive SEO management for ApostropheCMS. Essential meta fields, Google Analytics integration, and automated robots.txt generation—everything you need to boost your search rankings and drive organic traffic.
This version requires the latest ApostropheCMS. When adding this module to an existing project, run npm update to ensure all ApostropheCMS modules are up-to-date.
npm install @apostrophecms/seo
Configure the module in your app.js file:
import apostrophe from 'apostrophe';
apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {}
}
});
Important: For proper SEO functionality, you must also configure your site's base URL. See the Setting the Base URL section below.
The module automatically adds an "SEO" tab to all page and piece editors containing:
Enable Google Analytics tracking by configuring your global module:
import apostrophe from 'apostrophe';
apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleAnalytics: true
}
}
}
});
This adds a field in the global configuration for entering your Google Analytics Measurement ID (e.g., G-XXXXXXXXXX), which you can find in your Google Analytics account.
For advanced tracking and marketing campaigns:
import apostrophe from 'apostrophe';
apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleTagManager: true
}
}
}
});
This adds a Google Tag Manager container ID field to your global configuration. Enter your GTM container ID (e.g., GTM-XXXXXXX), which you can find in your Google Tag Manager account, to enable tracking.
Verify your site ownership for Google Search Console:
import apostrophe from 'apostrophe';
apostrophe({
root: import.meta,
shortName: 'my-project',
modules: {
'@apostrophecms/seo': {},
'@apostrophecms/global': {
options: {
seoGoogleVerification: true
}
}
}
});
This adds a Google Site Verification ID field to your global configuration. Enter your verification meta tag content (obtained from Google Search Console) in the global settings to verify site ownership.
This step is required for proper canonical link generation and SEO performance. If using ApostropheCMS hosting, this is set automatically. If you are self-hosted, configure your site's base URL as shown for accurate canonical links and proper search engine indexing.
Via environment variable (recommended):
export APOS_BASE_URL=https://yoursite.com
Via configuration file:
// data/local.js
export default {
baseUrl: 'https://yoursite.com',
modules: {
// other module configuration
}
};
For multisite projects using ApostropheCMS Assembly:
If you're managing multiple sites with our Assembly platform, the base URL is automatically configured through the baseUrlDomains option. Learn more about Assembly multisite hosting.
To disable SEO fields for specific page or piece types:
// modules/my-piece-type/index.js
export default {
extend: '@apostrophecms/piece-type',
options: {
// Disables SEO tab
seoFields: false
}
};
The following modules disable SEO fields by default:
@apostrophecms/global@apostrophecms/user@apostrophecms/image@apostrophecms/image-tag@apostrophecms/file@apostrophecms/file-tag"Canonical links" are useful when a piece or page should not be considered the official version of a document, and you would prefer that search engines look elsewhere. This feature is always available for pages.
As described on Moz.com: “A canonical tag, also known as 'rel canonical', is a method for informing search engines that a certain URL, referred to as the canonical URL, is the master copy of a page.” Using the canonical tag prevents problems caused by identical or 'duplicate' content appearing on multiple URLs. Practically speaking, the canonical tag tells search engines which version of a URL you want to appear in search results.
If you wish to have this feature for a piece type, you will need to specify the seoCanonicalTypes option to that piece type module, as an array of types that the editor can choose from.
// modules/article/index.js
export default {
extend: '@apostrophecms/piece-type',
options: {
label: 'Article',
// Allow editors to select a published page or `topic` piece as canonical references
seoCanonicalTypes: [ '@apostrophecms/page', 'topic' ]
}
};
This adds additional fields in the SEO tab for choosing a canonical document for search engines to consider instead.
Note that you cannot link to specific page-types, only all pages through
@apostrophecms/page, but you can link to specific piece-types.
The module automatically provides a /robots.txt route. By default, it returns content that allows all search engines to index your site:
User-agent: *
Disallow:
By clicking on the global settings gear button in the UI you can choose to change this to disallow search engine indexing:
User-agent: *
Disallow: /
You can also select to add a custom string for your robots.txt. This allows you finer control over what sections of your site can be indexed and by which bots.
Note that if you allow search engines to index your site, you can still set noindex and/or nofollow on a per-page basis from the SEO tab of individual page editing modals. If you disallow indexing of your site, settings for individual pages will be ignored.
A physical robots.txt file in public/robots.txt, or sites/public/robots.txt in an Assembly project, will override any settings made in this module. If you don't want a one-size-fits-all policy for all sites, don't use a physical file.
Track 404 errors in Google Analytics by adding this to your notFound.html template:
{% block extraBody %}
{{ super() }}
{% include "@apostrophecms/seo:404.html" %}
{% endblock %}
Note: If you already have an
extraBodyblock in your template, just add the{% include "@apostrophecms/seo:404.html" %}line inside it. The{{ super() }}call is optional if you're extending an existing block from another template.
This automatically sends 404 events to Google Analytics when a tracking ID is configured, helping you identify broken links and problematic URLs.
| Name | Description | Module Effected | Module Option |
|---|---|---|---|
seoTitle | Title attribute, populates <meta name="title" /> tag | @apostrophecms/doc-type | Enabled by default |
seoDescription | Description attribute, populates <meta name="description" /> tag | @apostrophecms/doc-type | Enabled by default |
seoRobots | Robots attribute, populates <meta name="robots" /> tag | @apostrophecms/doc-type | Enabled by default |
_seoCanonical | Canonical URL, populates <link rel="canonical" /> tag | @apostrophecms/page-type | Enabled by default |
seoGoogleTagManager | Google Tag Manager Container ID | @apostrophecms/global | seoGoogleTagManager: true |
seoGoogleTrackingId | Google Analytics ID | @apostrophecms/global | seoGoogleAnalytics: true |
seoGoogleVerificationId | Google Verification ID, populates <meta name="google-site-verification" /> | @apostrophecms/global | seoGoogleVerification: true |
Want to supercharge your SEO workflow? Create an account on Apostrophe Workspaces and upgrade to ApostropheCMS Pro now. Get access to the SEO Assistant with AI-powered content optimization and additional Pro modules:
The SEO Assistant analyzes your page content and generates optimized meta titles and descriptions using advanced AI, making professional SEO accessible to content creators of all skill levels.
Contact us to learn more about ApostropheCMS Pro and unlock AI-powered SEO optimization.
Running multiple websites with shared content and branding? Consider ApostropheCMS Assembly for enterprise multisite management:
Perfect for agencies, franchises, or organizations managing multiple branded websites with consistent functionality but unique content and design.
Learn more about the multisite extension, Assembly licensing or contact our team to discuss your multisite needs.
| Feature | Status |
|---|---|
| SEO Meta fields for pages and pieces | ✅ Implemented |
| Google Analytics & Tag Manager integration | ✅ Implemented |
| Automated robots.txt generation | ✅ Implemented |
| SEO Assistant (AI-powered) | 🚀 Available in Pro |
| SEO Page Scanner | 🚧 Under development |
Made with ❤️ by the ApostropheCMS team. Found this useful? Give us a star on GitHub! ⭐
FAQs
SEO Tools for ApostropheCMS
We found that @apostrophecms/seo demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 8 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.