Astro
How to integrate Webcore into Astro
This documentation helps you guide through the steps to integrate Webcore into your Astro project. The easiest way to get started is to use the CLI. Run the following command in your terminal and follow the prompts to install Astro with Webcore:
npm create webcore@latest
If you’d like to integrate Webcore into an existing project, you can follow the steps below to configure it manually.
-
Create a new Astro Project
If you don’t have an existing project, start by creating a new Astro project by running the following command in your terminal:
Terminal window npm create astro@latest -
Add Webcore
Add Webcore as a dependency by running the following command in your terminal:
Terminal window npm i webcoreui -
Update Astro Configuration
Update your Astro configuration file with the following lines:
astro.config.mjs export default defineConfig({vite: {ssr: {noExternal: ['webcoreui']}}})This rule prevents Webcore from being externalized. Without this rule, Astro components will not be recognized by Vite. In case you’re using Astro 4.x, you might also need to add the following CSS rule:
astro.config.mjs export default defineConfig({vite: {ssr: { ... }css: {preprocessorOptions: {scss: {api: 'modern-compiler'}}}}})Webcore uses the latest API of Sass. Astro 4.x is based on a previous version of Vite which still uses the legacy API by default, which means starting the dev server can cause deprecation warnings logged to the terminal. To prevent this, the API must be set explicitly to
modern-compiler
in the Vite config.Deprecation warning logged without the above css rule in Astro 4.x Deprecation Warning: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.More info: https://sass-lang.com/d/legacy-js-api -
Create the CSS Configuration File
Add an empty
webcore.config.scss
file at the root of your project. You can read more about how you can configure your CSS using this file in the CSS Configuration section. -
Configure CSS
Create a
Layout.astro
component for your app that can hold global CSS for the default styles. Inside the component, setup default styles and fonts by adding the following mixin:Layout.astro <!doctype html><html lang="en"><head>...</head><body><slot /></body></html><style lang="scss">@use 'webcoreui/styles' as *;@include setup((fontRegular: '/fonts/Inter-Regular.woff2',fontBold: '/fonts/Inter-Bold.woff2'));</style>Make sure the path to your fonts are correctly configured. The above example assumes your fonts are present in the
public/fonts
directory.You can download the fonts Webcore uses from thepublic/fonts
directory. -
Using Components
That’s it! You’re all set to start using Webcore components in your Astro project. Import components from
webcoreui/astro
:pages/index.astro ---import { Alert } from 'webcoreui/astro'import Layout from '../components/Layout.astro'---<Layout><Alert theme="info">Webcore is ready</Alert></Layout>Then run your dev server using the following command to view your app:
Terminal window npm run devNote:
Using Svelte components inside Astro components may cause the following TypeScript error:
Property 'x' does not exist on type 'IntrinsicAttributes & ComponentConstructorOptions<ComponentProps>Related issue on GitHub: #425. As a temporary workaround, you can ignore these warnings using the
@ts-ignore
annotation, or using@ts-nocheck
for ignoring an entire Astro file where Svelte components may be used.
Source Code
Request improvement for this page