Components and Custom Code
Choose the right approach for a custom change, copy or wrap theme components, and understand how to maintain your local code through core updates.
Choose the smallest edit
Section titled “Choose the smallest edit”Use page JSON for content/options and the customer Astro route for section order. Create a local section for new content. Copy a core component when you want to maintain its HTML and Tailwind markup yourself.
Copy a registered component
Section titled “Copy a registered component”From the customer project root:
mkdir -p src/componentscp node_modules/@rtthemes/naturalife/components/FeatureGridSection.astro src/components/FeatureGridSection.astroOn systems without cp, copy the same file using your editor or file manager. Edit the local file, then preview. Existing virtual:naturalife/components/FeatureGridSection imports select it automatically, including package compositions that use that virtual name.
Selection order is:
- An explicit
componentsentry in the existing integration config. - An exact
src/components/Name.astromatch, including case. - The package default.
All 115 public component Astro files can be copied individually without copying helper implementations. Automatic discovery applies to 104 registered virtual component names. It does not recursively search other folders or arbitrary filenames. Invalid selected code/config reports an error instead of silently using the default. The dev server observes file additions, edits and removals.
For a different name or location, add a selection inside your existing naturalife() options:
components: { FeatureGridSection: './src/components/MyFeatures.astro',},Remove the explicit selection and the exact-name local file to return to the package default. Direct package imports bypass this selection mechanism.
Direct layout and content imports
Section titled “Direct layout and content imports”The other 11 exports are ArchivePagination, BlogPostLayout, ContentBody, ContentGallery, ContentImage, ContentTestimonials, Dialogs, FontHead, PageContentLayout, SeoHead and SiteLayout.
You can copy those files too, but select the copy with a local import at the call site. Their names do not gain automatic discovery. Templates also retain explicit templates selection; a same-name local file alone does not select a template.
Wrap the package default
Section titled “Wrap the package default”A local registered wrapper must import the direct default, never its own selected virtual path:
---import DefaultFeatures from '@rtthemes/naturalife/components/FeatureGridSection.astro';import type { ComponentProps } from 'astro/types';type Props = ComponentProps<typeof DefaultFeatures>;---<DefaultFeatures {...Astro.props} />Importing virtual:naturalife/components/FeatureGridSection from its own wrapper recurses. For other components, forward the props, slots and behavior hooks they actually support. A complete replacement document must retain the shared SEO/font/style head behavior.
Maintain your custom code
Section titled “Maintain your custom code”Do not edit node_modules/ or copy private helpers to change HTML. Delivered helpers are compiled JavaScript with type declarations; the public imports remain available to copied components.
Copied/customized components are customer-maintained and outside theme update compatibility and warranty coverage. Core updates do not merge, overwrite or repair them. Package children still called by a copy can change independently, so review the copy after every core update. See Updates and Recovery.
Get all RT-Themes designs, updates and support with a single Club license.
Join the Club