How to simply integrate TwicPics into your Astro project

In this guide, we'll leverage React's easy integration with Astro.js to set up and use TwicPics Components.

In less than 5 minutes, you will be able to exploit all TwicPics Components' power :

CLS Optimization
Ideal Compression
Layout Driven
Lazy Loading
LQIP
Pixel Perfect

This tutorial requires using Node.js v16.12.0 or higher.

Scaffold your new Astro Project

You can skip this part if you already have an existing project.

Setup Wizard

# create a new project with npm
npm create astro@latest

# create a new project with yarn
yarn create astro

Follow the instructions. Choose the "a few best practices" option and if all goes well, you should see a "Liftoff confirmed." message. You can now cd into your new project directory.

Start Astro

# using npm
npm run dev

# using yarn
yarn dev

If all goes well, Astro should now be serving your project on http://localhost:3000/ and you should see something like that:

If you get stuck at any point, please visit the official Astro page.

Adding React to your project

You can skip this step if you have already activated React in your Astro project.

Integration Wizard

Use one of these command lines to activate React in your Astro project.

# using npm
npx astro add react

# using yarn
yarn astro add react

Simply answer yes (Y) to each question and Astro should automatically configure your project.

Learn more about Astro Integrations.

Testing React integration

To verify that everything is working properly, we will create a little React component.

In the src/components folder, create a my-react-component.jsx file like:

// src/components/my-react-component.jsx
export const MyReactComponent = () => {
  return <div>🚀 I am a React Component 🚀</div>
}

Now, let's modify the main page of our project to include this React component.

// src/pages/index.astro
---
import Layout from '../layouts/Layout.astro';
import Card from '../components/Card.astro';
// import my-react-component
import { MyReactComponent } from '../components/my-react-component';
---

<Layout title="Welcome to Astro.">
  <main>
    <h1>Welcome to <span class="text-gradient">Astro</span></h1>
    <!-- Adds MyReactComponent to the template -->
    <MyReactComponent></MyReactComponent>
    <!-- ... -->
  </main>
</Layout>
<style>
  ...
</style>

If all goes well, you should see something like this:

React is now activated and working properly in your project.

If not, please refer to React Integration documentation.

Install and configure TwicPics Components

Now that React is up and running in your project, you can configure the React version of the TwicPics components.

In the following, we will use our test domain:https://demo.twic.pics
If you don't have a TwicPics domain yet, you can easily create your own for free.

Install TwicPics Components

Add the @twicpics/components package to your project:

# using npm
npm install @twicpics/components

# using yarn
yarn add @twicpics/components

Setting-up TwicPics Components

The configuration of the TwicPics components must be done at the main layout level of the application.

Modify the file src/layouts/Layout.astro as follows:

// src/layouts/Layout.astro
---
export interface Props {
  title: string;
}

const { title } = Astro.props;
---

<script>
  import "@twicpics/components/style.css";
  import { installTwicpics } from "@twicpics/components/react";
  installTwicpics({
    domain: "https://demo.twic.pics",
  });
</script>

<html lang="en">
<!-- file rest unchanged -->

TwicPics Components are now ready to be used: we can display our first image with all the power of TwicPics.

Using TwicPics Components in a React component

Let's reopen our little React component src/components/my-react-component.jsx and modify it as follows:

// src/components/my-react-component.jsx

// import TwicImg from react version of TwicPics components
// and use <TwicImg/> as a replacement for <img/> tag
import { TwicImg } from '@twicpics/components/react'

export const MyReactComponent = () => {
  return <TwicImg src="one-giant-leap.jpg" />
}

The image used here is https://assets.twicpics.com/examples/one-giant-leap.jpg (jpg - 2662x3697px - 1.69 Mo).

The network console shows us that we have loaded a webp - 520x520px - 51.9kB.

Our displayed media is :

ideally compressed.
perfectly adapted in size to its display area.
cropped in its container. This last one guarantees CLS optimization.

Note that here we have used TwicImg with no other properties than src.
Feel free to explore all other TwicImg properties.

Using TwicPics Components in .astro file

In the previous example, as a React developer, we used TwicImg in a React component. But with Astro, you can integrate TwicImg directly into an .astro file: page, component, and even layout.

For example, let's modify the src/components/Card.astro component of our project as follows:

---
// src/components/Card.astro
import { TwicImg } from "@twicpics/components/react";
export interface Props {
  title: string;
  src: string;
}
const { title, src } = Astro.props;
---
<li class="link-card">
  <a href="#">
    <h2>
      {title}
      <span>&rarr;</span>
    </h2>
    <TwicImg src={src} ratio="16/9" focus="auto" />
  </a>
</li>
<style>
<!-- file rest unchanged -->
</style>

Then let's update the page src/pages/index.astro that uses this modified component:

---
import Layout from '../layouts/Layout.astro';
import Card from '../components/Card.astro';
import { MyReactComponent } from '../components/my-react-component';
---

<Layout title="Welcome to Astro.">
    <main>
        <h1>Welcome to <span class="text-gradient">Astro</span></h1>
        <!-- Adds MyReactComponent to the template -->
        <MyReactComponent></MyReactComponent>
        <p class="instructions">
            To get start, open the directory <code>src/pages</code> in your project.<br />
            <strong>Code Challenge:</strong> Tweak the "Welcome to Astro" message above.
        </p>
        <ul role="list" class="link-card-grid">
            <Card
                href="https://docs.astro.build/"
                title="Earth"
                src="earth.jpg"
            />
            <Card
                href="https://astro.build/integrations/"
                title="Moon"
                src="moon.jpg"
            />
            <Card
                href="https://astro.build/themes/"
                title="Saturn"
                src="saturn.jpg"
            />
            <Card
                href="https://astro.build/chat/"
                title="Netpune"
                src="neptune.jpg"
            />
        </ul>
    </main>
</Layout>
<!-- file rest unchanged -->

This is what we should get:

There again, the network console shows us that our loaded images are :

ideally compressed
perfectly adapted in size to their display area
cropped in their container

What about LQIP?

There is one more thing to consider to fully use TwicPics Components in an Astro project.

By default, Astro removes all javascript code generated from the server-side pages. It is up to the developer to specify if (and when) javascript should be loaded client side. This is called partial hydration.

In our case, the LQIP functionality uses a small piece of javascript. So we have to use the client:load directive.

Let's modify src/components/Card.astro by adding client:load directive to our TwicImg React component:

// src/components/Card.astro
<TwicImg src={src} ratio="16/9" focus="auto" client:load />

Let's also modify src/pages/index.astrofile by adding client:load directive to our MyReactComponent React component:

// src/pages/index.astro
<!-- Adds MyReactComponent to the template -->
<MyReactComponent client:load/>

Here is the result:

TwicPics Components are now fully functional. Users will have a better experience: a blurry lightweight version of your media will be displayed until the final image is loaded.

Conclusion

You can now easily and efficiently manage your media in an Astro project.

You are free to use TwicPics Components within a classical React Component or, if you are more comfortable, directly in a page or an Astro component.

Feel free to visit this demonstration page to discover some of the many features TwicPics Components offer (smart cropping, driven layout, short video optimization...). They are free and open-source. Don't hesitate to test them for yourself. The only requirement to use them is to have a TwicPics account. If you don't already have one, you can easily create your own TwicPics account for free.