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']
        }
        css: {
            preprocessorOptions: {
                scss: {
                    api: 'modern-compiler'
                }
            }
        }
    }
})
```
- noExternal: This rule prevents Webcore from being externalized. Without this rule, Astro components will not be recognized by Vite.
- css: Webcore uses the latest API of Sass. Vite, however, 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
```
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
```
This rule can be removed in the future, once Vite switches its default settings to use the modern API.
- Related issue: 18164, Vite config
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 the public/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 dev
```
Note:
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

Open Starter Project on GitHub

<- Changelog Svelte ->

Request improvement for this page

Astro

Create a new Astro Project

Add Webcore

Update Astro Configuration

Create the CSS Configuration File

Configure CSS

Using Components

Source Code