As we saw in the last lesson, there are some really great existing Veep plugins available. And, if one exists that solves your problem, then great, no need to reinvent the wheel. But, in case you can't find a suitable plugin for your needs, I'd like to briefly show you how to create a simple Veep plugin for yourself. As an example, let's create a simple Markdown to View component, Veep Plugin.
The plugin will allow us to have a Markdown file, like this. and we'll add a heading of Hello World, and then maybe a paragraph. This is some Markdown. Then, we could import it as a view component, like this.
md, and then use it in the template as a component. Looking in the browser now, yeah, we can see that this doesn't work. Okay. let's create the plugin.
js. It's a convention to prefix your VitePlugin names with Vite-Plugin. And if it's meant to only work with a specific framework, to include that framework name after VitePlugin, like we did. Notice that while we're working on the plugin, the source code can live right here in our project.
All right, step one in this file is to export a function that accepts some user options. These user options will allow the user of the plugin to customize it with certain settings, and we'll put it to use in a minute. Next, we'll return the plugin object that allows us to pass certain information on to Veet about our plugin, and also hook into particular parts of the Veet lifecycle. First, in this object, we'll provide the name of the plugin.
This name is required and will show up in warnings and errors. Next, I want to use the enforce option to tell Vite that this should be one of the earlier plugins that runs. The pre value here tells Vite to run this plugin before, one, the Vite core plugins, two, user plugins without the enforce value, and three, the Vite build plugins. If we had used post, it would force the plugin to run.
after those steps. This is important for our use case because we will be dumping the markdown into the template of a virtual view file that we want the view plugin to then handle as it would any normal view file. Thus we want our plugin to run before the view plugin. Okay so now the question is how do we actually spit out this template?
Well to do that we need to use the Vite transform hook. transform receives two arguments, the raw file contents and the file ID. For files that really exist in the file system, this ID is the file name with its absolute path. However, this transform hook runs for every single file being imported in our project.
So let's limit it to only apply to the files ending with the markdown extension using a regular expression. Then we can return that view template. with the raw file contents inside. As is, this would only spit out the raw markdown into the template.
In order to parse the markdown into HTML, let's install and use the open source package marked. First, I'll install it npm install dash d marked. Then we'll import it and use it in the plugin. Great!
That just about does it for the basic functionality of the plugin. But, just to show you how a user option might work, let's make the wrapper element that's hardcoded as a div here, configurable by the plugin user. First, I'll provide an option wrapper element, and give it a default value of div. Then, I'll extract the wrapper element using object destructuring, and alias it to L, just for brevity's sake.
Lastly, I'll replace the hardcoded divs with the L variable. Very nice. All that's left to do now is actually use the plugin. config file and import our custom plugin.
Now we can use it in the plugins option. Also, one more thing actually. Since we're relying on the Vue plugin to take the template from the Markdown file, we'll also need to tell the Vue plugin to include a file type that it doesn't normally process. We can do that with the Vue plugin include option.
And I think this is a perfectly acceptable solution. as this is actually exactly what one of those community templates for Markdown does. Alright, if we check things out in the browser now, things are no longer broken, and our Markdown appears on the page. Don't let the size of the H1 confuse you.
Let's just tell when stripping out the tag default styles. To prove it to you, let's inspect. And yeah, we can see the H1 there, along with the paragraph tag. And they're both wrapped in a div.
As an extra tip, If you'd like to get Tailwind working well with rich text and Markdown, you can check out the Tailwind CSS Typography plugin, and I've added a link to it in the description below. Okay, let's try out the wrapper element option. We'll say that we'd like to use a section instead of a div. When we inspect now, sure enough, we get the section.
Awesome. Lastly, we can go make a change in the Markdown file and see VEAT's hot module replacement. automatically updates the page. At this point, if this were a new and unique plugin, we could extract it to its own project, and share it via NPM, and we'd be good to reuse it in project after project.
In conclusion, this is just one example of what you can do with Veep plugins. There are many other possibilities, and you can learn more about what's possible in the Veep docs linked below. As we saw in the last lesson, there are some really great existing Veep plugins available. And, if one exists that solves your problem, then great, no need to reinvent the wheel.
But, in case you can't find a suitable plugin for your needs, I'd like to briefly show you how to create a simple Veep plugin for yourself. As an example, let's create a simple Markdown to View component, Veep Plugin. The plugin will allow us to have a Markdown file, like this. and we'll add a heading of Hello World, and then maybe a paragraph.
This is some Markdown. Then, we could import it as a view component, like this. md, and then use it in the template as a component. Looking in the browser now, yeah, we can see that this doesn't work.
Okay. let's create the plugin. js. It's a convention to prefix your VitePlugin names with Vite-Plugin.
And if it's meant to only work with a specific framework, to include that framework name after VitePlugin, like we did. Notice that while we're working on the plugin, the source code can live right here in our project. All right, step one in this file is to export a function that accepts some user options. These user options will allow the user of the plugin to customize it with certain settings, and we'll put it to use in a minute.
Next, we'll return the plugin object that allows us to pass certain information on to Veet about our plugin, and also hook into particular parts of the Veet lifecycle. First, in this object, we'll provide the name of the plugin. This name is required and will show up in warnings and errors. Next, I want to use the enforce option to tell Vite that this should be one of the earlier plugins that runs.
The pre value here tells Vite to run this plugin before, one, the Vite core plugins, two, user plugins without the enforce value, and three, the Vite build plugins. If we had used post, it would force the plugin to run. after those steps. This is important for our use case because we will be dumping the markdown into the template of a virtual view file that we want the view plugin to then handle as it would any normal view file.
Thus we want our plugin to run before the view plugin. Okay so now the question is how do we actually spit out this template? Well to do that we need to use the Vite transform hook. transform receives two arguments, the raw file contents and the file ID.
For files that really exist in the file system, this ID is the file name with its absolute path. However, this transform hook runs for every single file being imported in our project. So let's limit it to only apply to the files ending with the markdown extension using a regular expression. Then we can return that view template.
with the raw file contents inside. As is, this would only spit out the raw markdown into the template. In order to parse the markdown into HTML, let's install and use the open source package marked. First, I'll install it npm install dash d marked.
Then we'll import it and use it in the plugin. Great! That just about does it for the basic functionality of the plugin. But, just to show you how a user option might work, let's make the wrapper element that's hardcoded as a div here, configurable by the plugin user.
First, I'll provide an option wrapper element, and give it a default value of div. Then, I'll extract the wrapper element using object destructuring, and alias it to L, just for brevity's sake. Lastly, I'll replace the hardcoded divs with the L variable. Very nice.
All that's left to do now is actually use the plugin. config file and import our custom plugin. Now we can use it in the plugins option. Also, one more thing actually.
Since we're relying on the Vue plugin to take the template from the Markdown file, we'll also need to tell the Vue plugin to include a file type that it doesn't normally process. We can do that with the Vue plugin include option. And I think this is a perfectly acceptable solution. as this is actually exactly what one of those community templates for Markdown does.
Alright, if we check things out in the browser now, things are no longer broken, and our Markdown appears on the page. Don't let the size of the H1 confuse you. Let's just tell when stripping out the tag default styles. To prove it to you, let's inspect.
And yeah, we can see the H1 there, along with the paragraph tag. And they're both wrapped in a div. As an extra tip, If you'd like to get Tailwind working well with rich text and Markdown, you can check out the Tailwind CSS Typography plugin, and I've added a link to it in the description below. Okay, let's try out the wrapper element option.
We'll say that we'd like to use a section instead of a div. When we inspect now, sure enough, we get the section. Awesome. Lastly, we can go make a change in the Markdown file and see VEAT's hot module replacement.
automatically updates the page. At this point, if this were a new and unique plugin, we could extract it to its own project, and share it via NPM, and we'd be good to reuse it in project after project. In conclusion, this is just one example of what you can do with Veep plugins. There are many other possibilities, and you can learn more about what's possible in the Veep docs linked below.