components JS FRAMEWORKS how to
How to simply integrate TwicPics into your Astro project
Learn how to easily and efficiently manage your images and short videos in your Astro.js projects.
Miguel Beignon February 6, 2023 · 5 min read
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
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
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.
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.
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>→</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.astro
file 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.