Astro-UI:<XElement/>

XElement

Welcome to the home of XElement, an Astro only, Customisable HTML Web Component Generator.

Every Astronaut has their own set of highly specialised tools, just ask the Russian cosmonauts about their space ‘pen’.

XElement is meant to serve the same purpose; To give any astronaut a set of highly specialised tools that they need to build efficiently and effectively in their own space.

At it’s core is the ability for you to create all kinds of wonderful components to work with Astro, all from a single intuitive interface.

You can choose when and how to run JavaScript or TypeScript on the client-side and, have the all the dynamic behaviour encapsulated to that particular element.

XElement is built with Astro at its heart, fully respecting Astro’s island architecture experience and unique approach to Frontend Web Development.

We seek to give you the ability to expand on these concepts further to produce some very surprising results.

Onboarding

Before we proceed, lets make sure we are all up to speed with each other.

This guide makes some mild presumptions about you the reader, it is our intention to make this guide as easy and straight-forward as we possibly can do for the many without upsetting the few.

With that we appreciate that developers come in all manner of sizes and skill-levels.

Equally we respect that not everybody coming here is a seasoned Astronaut or familiar with some of the Frameworks that we would be talking about.

Don’t worry, here we strive for the polite middle-ground where we speak to everyone as an old friend, who are new to the field of web-development and are like every other self aspiring Astronaut, wanting to reach for the stars.

With that being said, we hope that you to have some amount of background knowledge in the following:

We urge you to follow along as much as possible when going through the examples, it helps to build up the muscle memory and will help you get going even quicker.

Most important to thing to remember when we are on our journey is never to panic, you got this, and we got you.

Live Demo

Click on the above link to be taken to an online demonstration of XElement in action.

Setting up Astro

You would need also need to have Astro setup and running in a project somewhere for this to work.

The truth is, XElement leverages a lot of the Astro Framework for its superpowers.

To get Astro setup in your project, enter npm init astro into your terminal window.

This would start the create-astro wizard, who’ll walk you through setting up your Astro project.

Choose from anyone of their starter templates provided and you are good to go.

For help and support with setting up Astro please do visit their Documentation for all Astro related truths.

Once setup, you are now able to start building your awesome Astro sites, and more importantly ready to use XElement to make them truly astronomical.

To setup XElement for yourself, from within your Astro project enter into the terminal:

npm i astro-xelement -D

Next, import into your .astro component file:

---
import XElement from 'astro-XElement'
---

That is it, you are now ready to start using XElement all over your project.

To start making your first components visit our ‘Getting Started’ guide to take you through making your first set of XElements

API reference

Here you will find all the XElement API reference points and information on how to use each one correctly. If you are ever stuck this is where you will most likely find the solutions that you seek for.

Guides

We have tried to document as best as we can all the things you can do with XElement and only provide best practices that one can take when using XElement.

As we grow, the documentation and its guides would also grow in step with each new advancement.

Its here inside each guide that we’ll explore all the concepts in greater detail.

We really want to help provide you with all the support and assistance that you need to get to grips with XElement and Astro.

Showcase

We love to see what you have made with XElement and Astro, you can showcase them directly within the Astro Discord Community in the ‘#Showcase’ channel, Tweet them at us, send them to us via Github or find us on Discord.

We will be looking to gather as many components together from users and be able to showcase them to a wider audience on your behalf.

Versions

XElement is now on v3.1.0.

This signifies the latest in a number of continuous improvements over successive generations of XElement during the past few months.

The third version has took a lot of energy and effort to work perfectly with Astro > v0.21. And will serve as the major release candidate for XElement and any future improvements that is made to it.

If you are using an older version of XElement although they may work, their support has been dropped and the earliest versions are no longer compatible with the current version of Astro. Please do look to make sure you have the most up-to-date version mentioned above.

The XElement tool itself is considered to be stable and safe for use in production environments.

Get Involved

When we began to create XElement with the burgeoning community of astronauts front and center to the development of XElement.

We care strongly about your experiences when you are using our product, and would look to support you as much as we possibly can in your endeavours.

This can only be done through mutual cooperation and communication between both parties.

Our github repo is active and would welcome any issues or PR requests to be made directly to it, this way we will be able to better deal with any user issues that you may face.

If you feel that there is something missing with the documentation or require better explanations, please do raise an issue with us through our Github repo.

Acknowledgements

This project owes a tremendous amount of gratitude and thanks to jonathantneal for his continuous support, guidance and hacking away at it. Pivotal in turning this whimsical fantasy into creation.

Special acknowledgement to the Astro Core team for their dedication and hard work towards building Astro as a fantastic framework for Frontend development.

Further Mentions

Its only fair to those who have assisted in this project from their support and input to being the first adopters, to be mentioned and appreciated for their individual contributions.

Thank you all for being patient. Brave when it came to testing and exploring XElement for us, and for helping us to realise its potential.

XElement was built of the back of good old curiosity, off-world magic and Irn-bru.

We assure you that no animals were harmed too seriously in the process.

How did we do?

Please take a moment to let us know what you thought of the documentation on this page!