SfSkills Domains Docs GitHub

Home / lwc / knowledge-article-lwc

knowledge-article-lwc

Use this skill when building Lightning Web Components that query, display, or accept feedback on Salesforce Knowledge articles — covering Knowledge__kav SOQL/SOSL retrieval via Apex, caching strategy, and Experience. NOT for Knowledge admin setup (article types, categories) or Einstein Article Recommendations — use admin/knowledge-base-administration.

Open the skill folder on GitHub

Knowledge Article LWC

Use this skill when a Lightning Web Component must retrieve and render Salesforce Knowledge article content, or accept user feedback such as thumbs-up/thumbs-down voting. It covers the correct Apex-backed retrieval pattern, Experience Cloud guest access requirements, and voting via custom Apex endpoints.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

No Dedicated Wire Adapter for Knowledge

Salesforce does not provide a Lightning Data Service wire adapter specifically for Knowledge articles. There is no @wire(getKnowledgeArticle) equivalent in the platform wire service. All Knowledge article retrieval must go through one of two paths:

  1. @wire(getRecord, { recordId, fields }) — works for single article records when you have a record ID and the running user has read access via sharing and data category visibility. Cannot be used for search-based retrieval.
  2. A custom @AuraEnabled(cacheable=true) Apex method that executes SOQL or SOSL against Knowledge__kav (or the custom article type) and returns the result. This is the standard pattern for all search-driven or list-based retrieval.

The cacheable=true annotation on Apex is mandatory for methods wired with @wire. Methods called imperatively (e.g., on button click) must NOT be annotated cacheable=true if they perform DML or call non-deterministic logic.

Knowledge__kav SOQL and SOSL Queries

Knowledge__kav represents published article versions. The key fields and constraints are:

Guest users execute queries in the Guest User context. Sharing rules for Knowledge in guest contexts are controlled by the org-wide default for Knowledge and by Guest User data category visibility settings in Setup > Channels > Data Category Visibility.

Experience Cloud Guest Access and Data Category Visibility

Experience Cloud guest users are unauthenticated visitors. They share a single Guest User record. For a Knowledge article to be visible to a guest user, ALL of the following must be true:

  1. The Knowledge org-wide sharing default allows read access to guests (Setup > Sharing Settings > Knowledge, or the site's guest sharing override).
  2. The article's IsVisibleInPkb field is true.
  3. The Guest User has data category visibility for the category the article is filed under (Setup > Data Category Visibility in Experience Workspaces, or org-level Guest Category Visibility).
  4. The Apex controller class must be marked without sharing or use an explicit with sharing declaration that permits guest access; otherwise the guest user context will deny the query.

Misconfiguring any one of these four conditions silently returns zero results rather than throwing an error, which makes this extremely difficult to debug without systematically checking each layer.

Voting and Feedback via Custom Apex

The standard Knowledge KnowledgeArticleViewStat and KnowledgeArticleVoteStat objects are read-only aggregates computed by the platform. To record a user vote, use the KbManagement.PublishingService Apex class (available in API 30+):

KbManagement.PublishingService.rateKnowledgeArticle(articleId, rating, userId);

Where rating is an integer from 1–5. There is no direct DML on KnowledgeArticleVoteStat. This method must be called from a non-cacheable @AuraEnabled Apex method (not wired) triggered by an explicit user action. The call counts against governor limits as a DML statement equivalent.

Common Patterns

Pattern: Wired SOSL Search Component

When to use: A search bar LWC where the user types a query and the component surfaces matching Knowledge articles in real time or on submit.

How it works:

  1. The LWC captures the user's search string from an input event.
  2. On input change (debounced) or on form submit, the component calls an imperative Apex method (not wired, because the search string is dynamic) decorated with @AuraEnabled(cacheable=true).
  3. The Apex method runs a SOSL query against Knowledge__kav scoped to PublishStatus = 'Online' and the appropriate channel visibility flag.
  4. The Apex method returns a List<Knowledge__kav> (or a wrapper DTO) to the component.
  5. The component renders results using for:each iteration in the HTML template.

Why not the alternative: Using @wire with a reactive property for the search string works, but it fires immediately on every keystroke. An imperative call with client-side debounce gives better UX and reduces Apex invocations.

Pattern: Single Article Display via getRecord Wire

When to use: A detail page component where the article ID is available via @api recordId from the record page (e.g., an Experience Cloud article detail page).

How it works:

  1. Declare the component with @api recordId.
  2. Use @wire(getRecord, { recordId: '$recordId', fields: FIELDS }) where FIELDS is an array of field references imported from @salesforce/schema.
  3. Extract field values using getFieldValue from lightning/uiRecordApi.
  4. Render the body HTML using lightning-formatted-rich-text (not innerHTML — see anti-patterns).

Why not the alternative: A custom SOQL Apex call for a single known record ID introduces unnecessary overhead. getRecord is served from Lightning Data Service cache and does not count against Apex limits for simple field reads.

Decision Guidance

SituationRecommended ApproachReason
Single article detail page, record ID in URL@wire(getRecord) with lightning/uiRecordApiUses LDS cache, no Apex limits consumed
Search-driven article listImperative @AuraEnabled(cacheable=true) Apex + SOSLDynamic input cannot be wired declaratively without complex reactive property management
Filtered article list (category, channel)@AuraEnabled(cacheable=true) Apex + SOQL with WITH DATA CATEGORYOnly SOQL supports structured data category filtering
Experience Cloud guest usersApex controller marked without sharing, guest data category visibility configuredGuest user context lacks sharing privileges; declarative visibility must be set explicitly
User voting / ratingNon-cacheable @AuraEnabled Apex calling KbManagement.PublishingService.rateKnowledgeArticleNo DML or LDS mutation API for Knowledge votes; platform service method is the only supported path
Rendering rich text article bodylightning-formatted-rich-text value={bodyField}Prevents XSS from unescaped HTML; never use innerHTML for Knowledge body content

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Confirm the article object and fields: Identify the article type API name (Knowledge__kav or custom), required fields (Title, Summary, Body, channel flags, language), and whether multi-language is enabled. Check Setup > Knowledge Settings.
  2. Determine the target surface and access model: Identify whether the component runs on an internal app page, an Experience Cloud authenticated page, or a guest-accessible page. For guest access, check Guest User data category visibility and sharing settings before writing any code.
  3. Choose the retrieval pattern: Use @wire(getRecord) for single known-record-ID detail pages. Use an imperative @AuraEnabled(cacheable=true) Apex method with SOSL for search, or SOQL with WITH DATA CATEGORY for category-scoped list views.
  4. Write the Apex controller: Implement @AuraEnabled(cacheable=true) retrieval methods. For Experience Cloud guest scenarios, declare the class without sharing and filter IsVisibleInPkb = true. For voting, implement a separate non-cacheable @AuraEnabled method calling KbManagement.PublishingService.rateKnowledgeArticle.
  5. Build the LWC: Import Apex methods with @salesforce/apex. Use @wire for cacheable methods bound to reactive properties, or call methods imperatively inside event handlers. Render body content exclusively with lightning-formatted-rich-text.
  6. Test Experience Cloud guest access end to end: Preview the site as a guest user, not just as an admin. Admin previews bypass sharing and category visibility. A dedicated guest-context test is mandatory before marking complete.
  7. Write Apex tests: Cover both the happy path and the case where no articles match (empty list return). Test without sharing methods explicitly. Aim for 90%+ coverage on the Apex controller.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. No wire adapter for Knowledge content — There is no platform-provided @wire adapter for Knowledge articles beyond getRecord. Developers who search LWC docs for a dedicated Knowledge wire adapter will not find one; all search and list retrieval must go through custom Apex.
  2. Guest user silently returns zero records — When data category visibility is not configured for the Guest User profile, SOQL queries against Knowledge__kav return an empty list without throwing an exception. This masquerades as "no matching articles" when the real issue is a missing visibility grant.
  3. WITH DATA CATEGORY clause cannot be combined with all SOQL features — WITH DATA CATEGORY is mutually exclusive with aggregate functions and certain subqueries. Attempting SELECT COUNT(Id) FROM Knowledge__kav WITH DATA CATEGORY ... throws a compile-time error.
  4. KnowledgeArticleVoteStat is read-only — There is no DML path to insert or update vote records. The only supported method to record a vote is KbManagement.PublishingService.rateKnowledgeArticle. LLMs frequently generate insert or upsert statements against this object, which fail at runtime.
  5. Admin Experience Cloud preview bypasses sharing — Testing a Knowledge LWC as a site administrator in Experience Builder preview does not replicate guest user sharing or category visibility. Articles that appear in admin preview can be invisible to actual guest users. Always test in an incognito browser session against the live or preview site URL.

Output Artifacts

ArtifactDescription
KnowledgeArticleController.clsApex class with @AuraEnabled(cacheable=true) retrieval methods and a non-cacheable voting method
KnowledgeArticleControllerTest.clsApex test class with happy path and empty-result coverage
knowledgeArticleList/LWC bundle for search and list display of Knowledge articles
knowledgeArticleDetail/LWC bundle for single article detail rendering
Setup checklistDocumented data category visibility and guest sharing configuration steps

Package files