Skip to content

Commit 879b101

Browse files
kavindadimuthukavindadimuthu
committed
Add QUICKSTART and README files for Vue.js SDK with integration instructions
1 parent 55d5a80 commit 879b101

File tree

2 files changed

+420
-0
lines changed

2 files changed

+420
-0
lines changed

‎packages/vue/QUICKSTART.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
# `@asgardeo/vue` Quickstart
2+
3+
This guide will help you quickly integrate Asgardeo authentication into your Vue.js application.
4+
5+
## Prerequisites
6+
7+
- [Node.js](https://nodejs.org/en/download) (version 16 or later. LTS version recommended)
8+
- An [Asgardeo account](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/)
9+
- Basic knowledge of Vue 3 and the Composition API
10+
11+
## Step 1: Configure an Application in Asgardeo
12+
13+
1. **Sign in to Asgardeo Console**
14+
- Go to [Asgardeo Console](https://console.asgardeo.io/)
15+
- Sign in with your Asgardeo account
16+
17+
2. **Create a New Application**
18+
- Click **Applications** in the left sidebar
19+
- Click **+ New Application**
20+
- Choose **Single Page Application (SPA)**
21+
- Enter your application name (e.g., "My Vue App")
22+
23+
3. **Note Down Your Credentials from the `Quickstart` tab**
24+
- Copy the **Client ID** from the application details
25+
- Note your **Base URL** (ex: `https://api.asgardeo.io/t/<your-organization-name>`)
26+
27+
4. **Configure Application Settings from the `Protocol` tab**
28+
- **Authorized redirect URLs**: Add your application URLs
29+
- `https://localhost:5173`
30+
- **Allowed origins**: Add the same URLs as above
31+
- Click **Update** to save the configuration
32+
33+
## Step 2: Create a Vue Application
34+
35+
If you don't have a Vue application set up yet, you can create one using `create-vue`:
36+
37+
```bash
38+
# Using npm
39+
npm create vue@latest vue-sample
40+
41+
# Using pnpm
42+
pnpm create vue@latest vue-sample
43+
44+
# Using yarn
45+
yarn create vue vue-sample
46+
```
47+
48+
When prompted, enable TypeScript for a better development experience.
49+
50+
Alternatively, using Vite:
51+
52+
```bash
53+
# Using npm
54+
npm create vite@latest vue-sample --template vue-ts
55+
56+
# Using pnpm
57+
pnpm create vite@latest vue-sample --template vue-ts
58+
59+
# Using yarn
60+
yarn create vite vue-sample --template vue-ts
61+
```
62+
63+
Navigate to your project:
64+
65+
```bash
66+
cd vue-sample
67+
```
68+
69+
## Step 3: Install the SDK
70+
71+
Install the Asgardeo Vue SDK in your project:
72+
73+
```bash
74+
# Using npm
75+
npm install @asgardeo/vue
76+
77+
# Using pnpm
78+
pnpm add @asgardeo/vue
79+
80+
# Using yarn
81+
yarn add @asgardeo/vue
82+
```
83+
84+
## Step 4: Configure the Provider
85+
86+
Register the Asgardeo plugin and wrap your application with the `AsgardeoProvider` in your main entry file (`src/main.ts`):
87+
88+
```ts
89+
import { createApp } from 'vue'
90+
import './style.css'
91+
import App from './App.vue'
92+
import { AsgardeoPlugin, AsgardeoProvider } from '@asgardeo/vue'
93+
94+
const app = createApp(App)
95+
96+
app.use(AsgardeoPlugin, {
97+
baseUrl: '<your-organization-base-url>',
98+
clientId: '<your-app-client-id>',
99+
})
100+
101+
app.mount('#app')
102+
```
103+
104+
Replace:
105+
- `<your-organization-base-url>` with the Base URL you noted in Step 1 (e.g., `https://api.asgardeo.io/t/<your-organization-name>`)
106+
- `<your-app-client-id>` with the Client ID from Step 1
107+
108+
Then wrap your app component with the `AsgardeoProvider` in `src/App.vue`:
109+
110+
```vue
111+
<script setup>
112+
import { AsgardeoProvider } from '@asgardeo/vue'
113+
</script>
114+
115+
<template>
116+
<AsgardeoProvider>
117+
<!-- Your application content goes here -->
118+
</AsgardeoProvider>
119+
</template>
120+
```
121+
122+
## Step 5: Add Sign-in & Sign-out to Your App
123+
124+
Update your `src/App.vue` to include sign-in and sign-out functionality:
125+
126+
```vue
127+
<script setup lang="ts">
128+
import { SignedIn, SignedOut, SignInButton, SignOutButton } from '@asgardeo/vue'
129+
</script>
130+
131+
<template>
132+
<div>
133+
<SignedIn>
134+
<SignOutButton />
135+
</SignedIn>
136+
<SignedOut>
137+
<SignInButton />
138+
</SignedOut>
139+
</div>
140+
</template>
141+
142+
<style scoped>
143+
/* Your custom styles */
144+
</style>
145+
```
146+
147+
## Step 6: Display User Information
148+
149+
You can also display user information by using the `User` component and the `useUser` composable:
150+
151+
```vue
152+
<script setup lang="ts">
153+
import { SignedIn, SignedOut, SignInButton, SignOutButton, User } from '@asgardeo/vue'
154+
import { useUser } from '@asgardeo/vue'
155+
156+
const { user, isLoading } = useUser()
157+
</script>
158+
159+
<template>
160+
<div>
161+
<SignedIn>
162+
<div v-if="!isLoading" class="user-info">
163+
<h1>Welcome, {{ user?.username }}</h1>
164+
<p>Email: {{ user?.email }}</p>
165+
</div>
166+
<div v-else>
167+
Loading user information...
168+
</div>
169+
<SignOutButton />
170+
</SignedIn>
171+
<SignedOut>
172+
<SignInButton />
173+
</SignedOut>
174+
</div>
175+
</template>
176+
177+
<style scoped>
178+
.user-info {
179+
padding: 1rem;
180+
border: 1px solid #e0e0e0;
181+
border-radius: 4px;
182+
margin-bottom: 1rem;
183+
}
184+
185+
h1 {
186+
margin: 0 0 0.5rem 0;
187+
font-size: 1.5rem;
188+
}
189+
190+
p {
191+
margin: 0;
192+
color: #666;
193+
}
194+
</style>
195+
```
196+
197+
### Using the User Render Function Pattern
198+
199+
Alternatively, you can use the `User` component with a render function:
200+
201+
```vue
202+
<script setup lang="ts">
203+
import { SignedIn, SignedOut, SignInButton, SignOutButton, User } from '@asgardeo/vue'
204+
</script>
205+
206+
<template>
207+
<div>
208+
<SignedIn>
209+
<User v-slot="{ user, isLoading }">
210+
<div v-if="!isLoading" class="user-info">
211+
<h1>Welcome, {{ user.username }}</h1>
212+
<p>Email: {{ user.email }}</p>
213+
</div>
214+
<div v-else>
215+
Loading user information...
216+
</div>
217+
</User>
218+
<SignOutButton />
219+
</SignedIn>
220+
<SignedOut>
221+
<SignInButton />
222+
</SignedOut>
223+
</div>
224+
</template>
225+
```
226+
227+
## Step 7: Try Login
228+
229+
Run your application and test the sign-in functionality. You should see a "Sign In" button when you're not signed in, and clicking it will redirect you to the Asgardeo sign-in page.
230+
231+
```bash
232+
# Using npm
233+
npm run dev
234+
235+
# Using pnpm
236+
pnpm dev
237+
238+
# Using yarn
239+
yarn dev
240+
```
241+
242+
Open your browser and navigate to `http://localhost:5173` (or the port shown in your terminal). Click the "Sign In" button to test the authentication flow.
243+
244+
## Step 8: Handle Callback
245+
246+
The SDK automatically handles the OAuth callback redirect. Make sure your application loads correctly after returning from Asgardeo. For custom callback handling, you can use the `Callback` component:
247+
248+
```vue
249+
<script setup lang="ts">
250+
import { Callback } from '@asgardeo/vue'
251+
</script>
252+
253+
<template>
254+
<div>
255+
<Callback />
256+
</div>
257+
</template>
258+
```
259+
260+
## Next Steps
261+
262+
🎉 **Congratulations!** You've successfully integrated Asgardeo authentication into your Vue app.
263+
264+
### What to explore next:
265+
266+
- **[API Documentation](https://wso2.com/asgardeo/docs/sdks/vue/overview)** - Learn about all available composables and components
267+
- **[Composables Guide](https://wso2.com/asgardeo/docs/sdks/vue/composables)** - Master the composable API (`useUser`, `useOrganization`, etc.)
268+
- **[Custom Styling](https://wso2.com/asgardeo/docs/sdks/vue/customization/styling)** - Customize the appearance of authentication components
269+
- **[Protected Routes](https://wso2.com/asgardeo/docs/sdks/vue/protected-routes)** - Implement route-level authentication
270+
- **[Organizations/Workspaces](https://wso2.com/asgardeo/docs/sdks/vue/organizations)** - Implement multi-tenancy features
271+
- **[User Profile Management](https://wso2.com/asgardeo/docs/sdks/vue/user-profile)** - Access and manage user profile data
272+
- **[Social Login](https://wso2.com/asgardeo/docs/sdks/vue/social-login)** - Enable sign-in with Google, GitHub, Microsoft, and Facebook
273+
274+
## Common Issues
275+
276+
### Redirect URL Mismatch
277+
- **Problem**: Getting errors about redirect URI not matching
278+
- **Solution**: Ensure your redirect URLs in Asgardeo match your local/production URLs exactly (including protocol and port)
279+
280+
### CORS Errors
281+
- **Problem**: Getting CORS-related errors in the console
282+
- **Solution**: Make sure to add your domain to the "Allowed Origins" in your Asgardeo application settings
283+
284+
### Client ID Not Found
285+
- **Problem**: Authentication fails with "Client ID is invalid"
286+
- **Solution**: Double-check that you're using the correct Client ID from your Asgardeo application and that it's properly configured in the plugin options
287+
288+
### Plugin Not Registered
289+
- **Problem**: Vue warns about plugin not being registered
290+
- **Solution**: Make sure you've called `app.use(AsgardeoPlugin, { ... })` before mounting your app
291+
292+
### State Not Updating
293+
- **Problem**: User state doesn't update after sign-in
294+
- **Solution**: Ensure you're using the composable (`useUser`) inside a component wrapped with `AsgardeoProvider`
295+
296+
## More Resources
297+
298+
- [Asgardeo Documentation](https://wso2.com/asgardeo/docs/)
299+
- [Vue.js Documentation](https://vuejs.org/)
300+
- [SDK Examples](../../samples/)
301+
- [GitHub Repository](https://github.com/asgardeo/asgardeo-auth-vue-sdk)
302+
303+
## Getting Help
304+
305+
If you encounter issues:
306+
1. Check the [FAQs](https://wso2.com/asgardeo/docs/faq/)
307+
2. Search [GitHub Issues](https://github.com/asgardeo/asgardeo-auth-vue-sdk/issues)
308+
3. Ask on the [WSO2 Community Forum](https://wso2.com/community/)
309+
4. Contact [Asgardeo Support](https://wso2.com/asgardeo/support/)

0 commit comments

Comments
 (0)