Skip to content

Commit 747bdbe

Browse files
joesphchangjoesphchang
committed
docs(javascript): added overview and ionic-core page
1 parent df879af commit 747bdbe

File tree

3 files changed

+173
-0
lines changed

3 files changed

+173
-0
lines changed

‎docs/javascript/ionic-core.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: 'Ionic Core Custom Components'
3+
sidebar_label: Ionic Core
4+
---
5+
6+
# Setting Up an Ionic Core Project with Vite (Vanilla JS)
7+
8+
This guide walks you through integrating [Ionic Core](https://ionicframework.com/docs/components) with a plain JavaScript (Vanilla) project using Vite. You'll get tree-shaking support, efficient bundle sizes, and a solid development experience.
9+
10+
# 1. Navigate to your desired directory and create a new Vite project
11+
Open your terminal and run:
12+
```shell
13+
npm create vite@latest my-vanilla-ionic-app -- --template vanilla
14+
```
15+
16+
# 2. Move into your project folder
17+
18+
```shell
19+
cd my-vanilla-ionic-app
20+
```
21+
22+
# 3. Install project dependencies
23+
Install both Vite's dependencies and Ionic Core:
24+
```shell
25+
npm install
26+
npm install @ionic/core
27+
```
28+
29+
# 5. Link Ionic CSS in `index.html`
30+
31+
Add the following `<link>` inside the `<head>` tag in index.html:
32+
33+
`<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core/css/ionic.bundle.css" />`
34+
35+
```html
36+
<!DOCTYPE html>
37+
<html lang="en">
38+
<head>
39+
<meta charset="UTF-8" />
40+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
41+
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
42+
<title>Ionic Core - Example</title>
43+
<link
44+
rel="stylesheet"
45+
href="https://cdn.jsdelivr.net/npm/@ionic/core/css/ionic.bundle.css"
46+
/>
47+
</head>
48+
<body>
49+
<ion-app>
50+
<ion-header>
51+
<ion-toolbar>
52+
<ion-title>My Ionic App</ion-title>
53+
</ion-toolbar>
54+
</ion-header>
55+
<ion-content class="ion-padding">
56+
<ion-button expand="block">Click Me</ion-button>
57+
</ion-content>
58+
</ion-app>
59+
</body>
60+
</html>
61+
```
62+
63+
# 6. Configure main.js for Tree-Shaking
64+
65+
- Open your project's main JavaScript entry file, which Vite typically names `main.js` in the project's root.
66+
- Add the Ionic `defineCustomElements` code to this file:
67+
68+
```js
69+
import { defineCustomElements } from '@ionic/core/loader';
70+
71+
const resourcesUrl = '/';
72+
73+
defineCustomElements(window, {
74+
components: [
75+
'ion-app',
76+
'ion-button',
77+
'ion-card',
78+
'ion-header',
79+
'ion-toolbar',
80+
'ion-title',
81+
'ion-content',
82+
],
83+
resourcesUrl: resourcesUrl,
84+
});
85+
```
86+
87+
# 7. Run the Development Server
88+
89+
Now that we're finally all set-up we can start our development server:
90+
91+
```shell
92+
npm run dev
93+
```
94+
95+
Your app will be available at http://localhost:5173. You should see Ionic-styled components working as expected.
96+
97+
9. Build for Production:
98+
99+
```shell
100+
npm run build
101+
```
102+
103+
The optimized production build will be output to the dist/ directory. Tree-shaking ensures only the components listed in main.js are included.
104+
105+
# Bonus: Framework Integrations
106+
107+
You can use Ionic Web Components in other frameworks that support custom elements.
108+
109+
Live examples below:
110+
111+
- [Svelte](https://stackblitz.com/edit/vitejs-vite-bp6vxnem?file=src%2FApp.svelte)
112+
113+
- [Alpine.JS](https://stackblitz.com/edit/vitejs-vite-kg36bvri?file=index.html)
114+
115+
- [Lit.JS](https://stackblitz.com/edit/vitejs-vite-twfn9ilc?file=package.json)
116+
117+
> Note: When integrating Ionic Core into projects using libraries such as Svelte, Alpine, or Lit, be aware that you won't have the built-in form and routing capabilities that are tightly coupled with Ionic's official Angular, React, and Vue framework integrations. You'll need to handle these aspects using the patterns and tools provided by your chosen library.

‎docs/javascript/overview.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: 'Ionic JavaScript Overview'
3+
sidebar_label: Overview
4+
---
5+
6+
<head>
7+
<title>Ionic JavaScript Overview | JavaScript Version Support and Tooling</title>
8+
<meta
9+
name="description"
10+
content="@ionic/javascript combines the Ionic experience with the tooling and APIs tailored to React developers. Learn more about version support and resources in our React Overview."
11+
/>
12+
</head>
13+
14+
import DocsCard from '@components/global/DocsCard';
15+
import DocsCards from '@components/global/DocsCards';
16+
17+
`@ionic/javascript` offers a powerful way to build cross-platform applications using JavaScript, and it integrates seamlessly with modern tooling like Vite. This combination allows you to leverage your existing JavaScript knowledge and the efficiency of Vite to create high-quality, performant apps with Ionic's extensive UI library and native capabilities.
18+
19+
## JavaScript Version Support
20+
21+
Ionic JavaScript, when used with Vite, supports the latest versions of JavaScript, ensuring you can use modern language features in your projects.
22+
23+
## JavaScript Tooling
24+
25+
Ionic JavaScript is designed to work hand-in-hand with the JavaScript CLI and popular tooling. When you choose Vite as your build tool, you gain access to its incredibly fast development server and optimized build process. You can continue to use your favorite JavaScript libraries for state management, testing, and more within this ecosystem.
26+
27+
## Native Tooling
28+
29+
[Capacitor](https://capacitorjs.com) is the official cross-platform runtime for Ionic JavaScript, enabling your apps to run natively on iOS, Android, and the web with a single codebase.
30+
31+
## Installation
32+
33+
```shell-session
34+
$ npm create vite@latest myApp -- --template vanilla
35+
$ npm install && npm install @ionic/core
36+
$ npm run dev
37+
```
38+
39+
## Resources
40+
41+
<DocsCards>
42+
43+
<DocsCard header="Ionic Core" href="ionic-core" icon="/icons/guide-quickstart-icon.png">
44+
<p>Quickly set-up your JavaScript application with Ionic Custom Components.</p>
45+
</DocsCard>
46+
47+
</DocsCards>

‎sidebars.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,15 @@ module.exports = {
9494
'angular/pwa',
9595
],
9696
},
97+
{
98+
type: 'category',
99+
label: 'JavaScript',
100+
collapsed: false,
101+
items: [
102+
'javascript/overview',
103+
'javascript/ionic-core',
104+
],
105+
},
97106
{
98107
type: 'category',
99108
label: 'React',

0 commit comments

Comments
 (0)