13 |
14 |
20 |
21 |
22 |
--------------------------------------------------------------------------------
/.github/workflows/actions.yml:
--------------------------------------------------------------------------------
1 | name: repo-checks
2 |
3 | on:
4 | pull_request:
5 | branches:
6 | - master
7 |
8 | jobs:
9 | main:
10 | runs-on: ubuntu-latest
11 | strategy:
12 | fail-fast: true
13 | matrix:
14 | include:
15 | - task: Lint
16 | allow_failures: false
17 | command: pnpm lerna run lint
18 | - task: Test
19 | allow_failures: false
20 | command: pnpm lerna run test
21 | steps:
22 | - uses: zendesk/checkout@v2
23 | - name: Use Node.js
24 | uses: zendesk/setup-node@v3
25 | with:
26 | node-version: 18.12.1
27 | - name: Install pnpm
28 | run: npm install -g pnpm
29 | - name: install packages
30 | run: pnpm install
31 | - name: ${{ matrix.env.TASK }}
32 | run: TASK=${{ matrix.env.TASK }} ${{ matrix.command }}
33 |
--------------------------------------------------------------------------------
/packages/react/src/app/App.jsx:
--------------------------------------------------------------------------------
1 | import { lazy, Suspense } from 'react'
2 | import { useLocation } from './hooks/useClient'
3 | import { TranslationProvider } from './contexts/TranslationProvider'
4 | import { DEFAULT_THEME, ThemeProvider } from '@zendeskgarden/react-theming'
5 |
6 | const TicketSideBar = lazy(() => import('./locations/TicketSideBar'))
7 | const Modal = lazy(() => import('./locations/Modal'))
8 |
9 | const LOCATIONS = {
10 | ticket_sidebar: TicketSideBar,
11 | modal: Modal,
12 | default: () => null
13 | }
14 |
15 | function App() {
16 | const location = useLocation()
17 | const Location = LOCATIONS[location] || LOCATIONS.default
18 |
19 | return (
20 |
21 |
22 | Loading...}>
23 |
24 |
25 |
26 |
27 | )
28 | }
29 |
30 | export default App
31 |
--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
1 | @zendesk/wattle
2 |
3 | ## Description
4 | Develop what, but also why this PR exists. The "Why" is as much, if not more important than the "What". I use this approach very often when I write commit messages, because if the code is clear enough it should already answer the "what" question. The "why" is often more subtle.
5 |
6 | ## Tasks
7 | - [ ] Write tests
8 |
9 | ## References
10 | [Jira](https://zendesk.atlassian.net/browse/VEG-XXX)
11 |
12 | ## Screenshots (if needed)
13 |
14 | Screenshot 1
15 |
16 |
17 |
18 |
19 | Screenshot 2
20 |
21 |
22 |
23 | ## Risks
24 | * [HIGH | medium | low] Does it work across browsers (including IE!)?
25 | * [HIGH | medium | low] Does it work in the different products (Support, Chat, Connect)?
26 | * [HIGH | medium | low] Are there any performance implications?
27 | * [HIGH | medium | low] Any security risks?
28 | * [HIGH | medium | low] What features does this touch?
29 |
--------------------------------------------------------------------------------
/packages/react/src/app/contexts/TranslationProvider.jsx:
--------------------------------------------------------------------------------
1 | import { createContext, useState, useEffect, useCallback } from 'react'
2 | import { useClient } from '../hooks/useClient'
3 | import I18n from '../../lib/i18n'
4 |
5 | export const TranslationContext = createContext()
6 |
7 | const i18n = new I18n()
8 |
9 | export function TranslationProvider({ children }) {
10 | const client = useClient()
11 | const [locale, setLocale] = useState()
12 | const [loading, setLoading] = useState(true)
13 |
14 | const loadTranslations = useCallback(
15 | async (currentLocale) => {
16 | const { currentUser } = await client.get('currentUser')
17 |
18 | const locale = currentLocale || currentUser.locale
19 |
20 | await i18n.loadTranslations(locale)
21 | setLoading(false)
22 | },
23 | [client]
24 | )
25 |
26 | useEffect(() => {
27 | loadTranslations(locale)
28 | }, [locale, loadTranslations])
29 |
30 | if (loading) return null
31 |
32 | return {children}
33 | }
34 |
--------------------------------------------------------------------------------
/packages/react/rollup/translations-loader-plugin.js:
--------------------------------------------------------------------------------
1 | import fs from 'fs/promises'
2 | import path from 'path'
3 |
4 | function translationFlatten(object, currentKeys = []) {
5 | const res = {}
6 |
7 | Object.keys(object).forEach((key) => {
8 | const value = object[key]
9 |
10 | if (typeof value === 'object') {
11 | if (value.title && value.value) {
12 | const flattenedKey = [...currentKeys, key].join('.')
13 | res[flattenedKey] = value.value
14 | } else {
15 | Object.assign(res, translationFlatten(value, [...currentKeys, key]))
16 | }
17 | } else {
18 | const flattenedKey = [...currentKeys, key].join('.')
19 | res[flattenedKey] = value
20 | }
21 | })
22 |
23 | return res
24 | }
25 |
26 | export default function TranslationsLoader() {
27 | return {
28 | name: 'translations-loader',
29 | transform: async (_, id) => {
30 | if (id.endsWith('.json') && id.includes(path.resolve(__dirname, '../src/translations'))) {
31 | const contentFile = await fs.readFile(id)
32 |
33 | const translations = JSON.parse(contentFile)
34 |
35 | return {
36 | code: `export default ${JSON.stringify(translationFlatten(translations))};`,
37 | map: null
38 | }
39 | }
40 | return null
41 | }
42 | }
43 | }
44 |
--------------------------------------------------------------------------------
/packages/react/src/app/locations/TicketSideBar.jsx:
--------------------------------------------------------------------------------
1 | import { useEffect } from 'react'
2 | import { useClient } from '../hooks/useClient'
3 | import { useI18n } from '../hooks/useI18n'
4 | import { Button } from '@zendeskgarden/react-buttons'
5 | import { Grid, Row } from '@zendeskgarden/react-grid'
6 | import { XL } from '@zendeskgarden/react-typography'
7 | import styled from 'styled-components'
8 |
9 | const TicketSideBar = () => {
10 | const client = useClient()
11 | const { t } = useI18n()
12 |
13 | const handleNewInstance = () => {
14 | client.invoke('instances.create', {
15 | location: 'modal',
16 | url: import.meta.env.VITE_ZENDESK_LOCATION,
17 | size: {
18 | width: '650px',
19 | height: '400px'
20 | }
21 | })
22 | }
23 |
24 | useEffect(() => {
25 | client.invoke('resize', { width: '100%', height: '450px' })
26 | }, [client])
27 |
28 | return (
29 |
30 |
31 | {t('ticket_sidebar.title')}
32 |
33 |
34 |
37 |
38 |
39 | )
40 | }
41 |
42 | const GridContainer = styled(Grid)`
43 | display: grid;
44 | gap: ${(props) => props.theme.space.sm};
45 | `
46 |
47 | export default TicketSideBar
48 |
--------------------------------------------------------------------------------
/packages/react/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "react_js-template",
3 | "private": true,
4 | "version": "0.0.1",
5 | "type": "module",
6 | "scripts": {
7 | "test": "vitest",
8 | "dev": "vite --port 3000",
9 | "watch": "vite build --watch --mode development",
10 | "build:dev": "vite build --mode development",
11 | "build": "vite build --mode production",
12 | "lint": "eslint . --ext js,jsx --max-warnings 0",
13 | "start": "zcli apps:server src",
14 | "start:prod": "zcli apps:server dist"
15 | },
16 | "dependencies": {
17 | "@zendeskgarden/css-bedrock": "^9.1.1",
18 | "@zendeskgarden/react-buttons": "^8.76.3",
19 | "@zendeskgarden/react-grid": "^8.76.3",
20 | "@zendeskgarden/react-theming": "^8.76.3",
21 | "@zendeskgarden/react-typography": "^8.76.3",
22 | "react": "^18.2.0",
23 | "react-dom": "^18.2.0",
24 | "styled-components": "^5.3.6"
25 | },
26 | "devDependencies": {
27 | "@testing-library/dom": "^10.1.0",
28 | "@testing-library/react": "^16.0.0",
29 | "@vitejs/plugin-react": "^4.2.1",
30 | "eslint": "^8.57.0",
31 | "eslint-config-prettier": "^9.1.0",
32 | "eslint-config-standard": "^17.1.0",
33 | "eslint-plugin-react": "^7.34.1",
34 | "eslint-plugin-react-hooks": "^4.6.0",
35 | "fast-glob": "^3.3.2",
36 | "jsdom": "^24.1.0",
37 | "prettier": "^3.2.5",
38 | "vite": "^6.3.5",
39 | "vitest": "^3.1.2"
40 | }
41 | }
42 |
--------------------------------------------------------------------------------
/packages/react/src/lib/i18n.js:
--------------------------------------------------------------------------------
1 | class I18n {
2 | constructor() {
3 | this.translations = {}
4 | }
5 |
6 | static getRetries(locale) {
7 | return [locale, locale.replace(/-.+$/, ''), 'en']
8 | }
9 |
10 | tryRequire = async (locale) => {
11 | try {
12 | const result = await import(`../translations/${locale}.json`)
13 | return result
14 | } catch (e) {
15 | return null
16 | }
17 | }
18 |
19 | loadTranslations = async (locale) => {
20 | const intentLocales = I18n.getRetries(locale)
21 |
22 | do {
23 | try {
24 | const importedTranslations = await this.tryRequire(intentLocales[0])
25 | if (importedTranslations.default) {
26 | this.translations = importedTranslations.default
27 | break
28 | }
29 | } catch (error) {
30 | intentLocales.shift()
31 | }
32 | } while (intentLocales.length)
33 | }
34 |
35 | t = (key, context = {}) => {
36 | const keyType = typeof key
37 | if (keyType !== 'string') throw new Error(`Translation key must be a string, got: ${keyType}`)
38 |
39 | const template = this.translations[key]
40 | if (!template) throw new Error(`Missing translation: ${key}`)
41 | if (typeof template !== 'string') throw new Error(`Invalid translation for key: ${key}`)
42 |
43 | return template.replace(/{{(.*?)}}/g, (_, match) => context[match] || '')
44 | }
45 | }
46 |
47 | export default I18n
48 |
--------------------------------------------------------------------------------
/packages/react/rollup/static-copy-plugin.js:
--------------------------------------------------------------------------------
1 | import path from 'node:path'
2 | import fs from 'node:fs/promises'
3 | import glob from 'fast-glob'
4 |
5 | export default function StaticCopy({ targets }) {
6 | let config = null
7 | return {
8 | name: 'static-copy',
9 | configResolved(resolvedConfig) {
10 | config = resolvedConfig
11 | },
12 | async writeBundle() {
13 | const rootPath = config.build.outDir
14 | await Promise.all(
15 | targets.map(async ({ src, dest, modifier = (data) => data }) => {
16 | const paths = await glob(src)
17 | const destinationPath = path.resolve(rootPath, dest)
18 | await processFiles(paths, destinationPath, modifier)
19 | })
20 | )
21 | }
22 | }
23 | }
24 |
25 | async function processFiles(paths, dest, modifier) {
26 | await Promise.all(
27 | paths.map(async (src) => {
28 | const isDirectory = (await fs.stat(src)).isDirectory()
29 | if (isDirectory) {
30 | return
31 | }
32 |
33 | const file = await fs.readFile(src)
34 | const fileName = path.basename(src)
35 | const modifiedFile = modifier(file, fileName)
36 |
37 | await ensureDirectory(dest)
38 | await fs.writeFile(path.resolve(dest, fileName), modifiedFile)
39 | })
40 | )
41 | }
42 |
43 | async function ensureDirectory(src) {
44 | try {
45 | await fs.mkdir(src, { recursive: true })
46 | } catch (error) {
47 | console.error(`Error creating directory ${src}: ${error}`)
48 | }
49 | }
50 |
--------------------------------------------------------------------------------
/packages/react/spec/app.test.jsx:
--------------------------------------------------------------------------------
1 | import { describe, expect, it, vi, beforeEach } from 'vitest'
2 | import { render, screen, cleanup, waitFor } from '@testing-library/react'
3 | import { ClientProvider } from '../src/app/contexts/ClientProvider'
4 | import App from '../src/app/App'
5 |
6 | const mockClient = {
7 | on: vi.fn((event, callback) => {
8 | if (event === 'app.registered') {
9 | setTimeout(callback, 0)
10 | }
11 | }),
12 | get: vi.fn().mockResolvedValue({ currentUser: { locale: 'en' } }),
13 | context: vi.fn().mockResolvedValue({ location: 'ticket_sidebar' }),
14 | invoke: vi.fn()
15 | }
16 |
17 | describe('App Components', () => {
18 | beforeEach(() => {
19 | cleanup()
20 | vi.clearAllMocks()
21 | document.body.innerHTML = ''
22 | vi.stubGlobal('ZAFClient', {
23 | init: vi.fn().mockReturnValue(mockClient)
24 | })
25 | })
26 |
27 | it('renders TicketSideBar and shows the correct content', async () => {
28 | render(
29 |
30 |
31 |
32 | )
33 |
34 | expect(mockClient.on).toHaveBeenCalledWith('app.registered', expect.any(Function))
35 |
36 | await waitFor(() => expect(screen.getByText('Hello from Ticket Side Bar')).toBeDefined())
37 | })
38 |
39 | it('renders Modal and shows the correct content', async () => {
40 | mockClient.context.mockImplementation(() => Promise.resolve({ location: 'modal' }))
41 | render(
42 |
43 |
44 |
45 | )
46 |
47 | expect(mockClient.on).toHaveBeenCalledWith('app.registered', expect.any(Function))
48 |
49 | await waitFor(() => expect(screen.getByText('Hello from Modal')).toBeDefined())
50 | })
51 | })
52 |
--------------------------------------------------------------------------------
/packages/react/vite.config.js:
--------------------------------------------------------------------------------
1 | import { fileURLToPath } from 'node:url'
2 | import { resolve, dirname } from 'node:path'
3 | import react from '@vitejs/plugin-react'
4 | import TranslationsLoader from './rollup/translations-loader-plugin'
5 | import { extractMarketplaceTranslation } from './rollup/modifiers/translations'
6 | import StaticCopy from './rollup/static-copy-plugin'
7 | import { defineConfig, loadEnv } from 'vite'
8 | import { changeLocation } from './rollup/modifiers/manifest'
9 | import process from 'node:process'
10 |
11 | const __filename = fileURLToPath(import.meta.url)
12 | const __dirname = dirname(__filename)
13 |
14 | export default ({ mode }) => {
15 | process.env = { ...process.env, ...loadEnv(mode, process.cwd()) }
16 | return defineConfig({
17 | base: './',
18 | plugins: [
19 | react(),
20 | TranslationsLoader(),
21 | StaticCopy({
22 | targets: [
23 | { src: resolve(__dirname, 'src/assets/*'), dest: './' },
24 | { src: resolve(__dirname, 'src/manifest.json'), dest: '../', modifier: changeLocation },
25 | {
26 | src: resolve(__dirname, 'src/translations/en.json'),
27 | dest: '../translations',
28 | modifier: extractMarketplaceTranslation
29 | }
30 | ]
31 | })
32 | ],
33 | root: 'src',
34 | test: {
35 | include: ['../{test,spec}/**/*.{test,spec}.{js,ts,jsx}'],
36 | exclude: ['**/node_modules/**', '**/dist/**'],
37 | globals: true,
38 | environment: 'jsdom'
39 | },
40 | build: {
41 | rollupOptions: {
42 | input: {
43 | main: resolve(__dirname, 'src/index.html')
44 | },
45 | output: {
46 | entryFileNames: `[name].js`,
47 | chunkFileNames: `[name].js`,
48 | assetFileNames: `[name].[ext]`
49 | },
50 | watch: {
51 | include: 'src/**'
52 | }
53 | },
54 | outDir: resolve(__dirname, 'dist/assets'),
55 | emptyOutDir: true
56 | }
57 | })
58 | }
59 |
--------------------------------------------------------------------------------
/packages/react/doc/i18n.md:
--------------------------------------------------------------------------------
1 | ## Using the I18n module
2 |
3 | The `useI18n` hook can be used to translate strings based on the current user's locale settings.
4 |
5 | ### Setup
6 |
7 | Put a `defaultLocale` property into your `manifest.json` file, otherwise it will use english (en)
8 |
9 | Add your translation files as `src/translations/XX.json` where `XX` is a locale such as `en-US`, `de`, or `zh`.
10 |
11 | A simple translation file might look like this:
12 |
13 | ```json
14 | {
15 | "hello": "Hello!",
16 | "goodbye": "Bye {{name}}!",
17 | "formal": {
18 | "farewell": "Farewell, friend."
19 | }
20 | }
21 | ```
22 |
23 | The "app" section in translation files is used *only* for public app listings in the Zendesk Marketplace. For these listings, we only allow English. The "app" sections in other translation files will be ignored.
24 |
25 | ### Initialization
26 |
27 | When you know which locale you want to use, call `useI18n`. An example of this can be found in the `/src/app/locations/Modal.jsx` component, where the `modal.title` will be translated.
28 |
29 | ```javascript
30 | import { XL } from '@zendeskgarden/react-typography'
31 | import { useI18n } from '../hooks/useI18n'
32 |
33 | const Modal = () => {
34 | const { t } = useI18n()
35 | return {t('modal.title')}
36 | }
37 |
38 | export default Modal
39 | ```
40 |
41 | ## Reference
42 |
43 | ### i18n.t(key, context)
44 |
45 | Returns a translated string using a key that is available in the relevant translation file (found in `src/translations/XX.json`).
46 |
47 | #### Arguments
48 |
49 | * `key`: The key assigned to the string in the JSON file. Dots may be used to access nested objects.
50 | * `context`: An object with named values to be interpolated into the resulting string.
51 |
52 | #### Returns
53 |
54 | A translated string generated by keying into the JSON file and interpolating any placeholders.
55 |
56 | #### Example
57 |
58 | ```javascript
59 | i18n.t('hello'); // returns "Hello!"
60 | i18n.t('goodbye', { name: 'Yak' }); // returns "Bye Yak!"
61 | i18n.t('formal.farewell'); // returns "Farewell, friend."
62 | ```
63 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | *Use of this software is subject to important terms and conditions as set forth in the License file*
2 |
3 | # App Scaffolds
4 |
5 | ## Description
6 | This repo contains various scaffolds to help developers build [apps for Zendesk products](https://developer.zendesk.com/apps/docs/apps-v2/getting_started).
7 |
8 | ## Getting Started
9 |
10 | ### Dependencies
11 | - [Node.js](https://nodejs.org/en/) >= 18.12.1
12 | - [Ruby](https://www.ruby-lang.org/) = 2.6.x
13 |
14 | ### Setup
15 | 1. Clone or fork this repo
16 | 2. Change (`cd`) into the `app_scaffolds` directory
17 | 3. Run `pnpm install`
18 | 4. `packages/react` contains react app scaffold. Please follow [React README](./packages/react/README.md)
19 | 5. `packages/basic` contains basic app scaffold. Please follow [Basic README](./packages/basic/README.md)
20 |
21 | To run your app locally in Zendesk, you need the latest [Zendesk Command Line Interface (ZCLI)](https://github.com/zendesk/zcli).
22 |
23 | ## Contribute
24 | * Put up a PR into the master branch.
25 | * CC and get a +1 from @zendesk/wattle.
26 |
27 | ## Bugs
28 | Submit Issues via [GitHub](https://github.com/zendesk/app_scaffolds/issues/new) or email support@zendesk.com.
29 |
30 | ## Useful Links
31 | Links to maintaining team, confluence pages, Datadog dashboard, Kibana logs, etc
32 | - https://developer.zendesk.com/
33 | - https://github.com/zendesk/zendesk_apps_tools
34 | - https://webpack.github.io
35 | - https://developer.zendesk.com/documentation/apps/build-an-app/using-react-in-a-support-app/
36 |
37 | ## Copyright and license
38 | Copyright 2018 Zendesk
39 |
40 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
41 |
42 | You may obtain a copy of the License at
43 | http://www.apache.org/licenses/LICENSE-2.0
44 | Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
45 |
--------------------------------------------------------------------------------
/packages/react/spec/i18n.test.js:
--------------------------------------------------------------------------------
1 | import { expect, it, describe, beforeAll, vi } from 'vitest'
2 | import I18n from '../src/lib/i18n'
3 |
4 | const i18n = new I18n()
5 |
6 | const mockEN = {
7 | one: 'the first translation',
8 | 'two.one': 'the second translation for: {{fname}}',
9 | 'two.two': 'the second translation for: {{fname}}-{{lname}}',
10 | 'three.one.one': 'the third translation from {{name}} for {{name}} should be {{name}}',
11 | four: {}
12 | }
13 |
14 | describe('i18n', () => {
15 | beforeAll(async () => {
16 | vi.mock('../src/translations/en.json', () => {
17 | return { default: mockEN }
18 | })
19 |
20 | vi.mock('../src/translations/fr.json', () => {
21 | throw new Error('no such file')
22 | })
23 |
24 | await i18n.loadTranslations('en')
25 | })
26 |
27 | describe('#loadTranslations', () => {
28 | it('return undefined for fr and fallback to en', async () => {
29 | await i18n.loadTranslations('fr')
30 | const result = i18n.t('one')
31 | expect(result).toBe('the first translation')
32 | })
33 | })
34 |
35 | describe('#tryRequire', () => {
36 | it('returns a json if the file exists', async () => {
37 | const result = await i18n.tryRequire('en')
38 |
39 | expect(result.default).toEqual(mockEN)
40 | })
41 |
42 | it("returns null if the file doesn't exist", async () => {
43 | const result = await i18n.tryRequire('fr')
44 | expect(result).toBe(null)
45 | })
46 | })
47 |
48 | describe('#t', () => {
49 | it('returns a string', () => {
50 | const result = i18n.t('one')
51 | expect(result).toBe('the first translation')
52 | })
53 |
54 | it('interpolates one string', () => {
55 | const result = i18n.t('two.one', {
56 | fname: 'Olaf'
57 | })
58 | expect(result).toBe('the second translation for: Olaf')
59 | })
60 |
61 | it('interpolates multiple strings', () => {
62 | const result = i18n.t('two.two', {
63 | fname: 'Olaf',
64 | lname: 'K'
65 | })
66 | expect(result).toBe('the second translation for: Olaf-K')
67 | })
68 |
69 | it('interpolates duplicates strings', () => {
70 | const result = i18n.t('three.one.one', {
71 | name: 'Olaf'
72 | })
73 | expect(result).toBe('the third translation from Olaf for Olaf should be Olaf')
74 | })
75 |
76 | it('should throw error if translate keyword is not string', function () {
77 | expect(() => {
78 | i18n.t({})
79 | }).toThrow()
80 | })
81 |
82 | it('should throw error if translation is not a string', function () {
83 | expect(() => {
84 | i18n.t('four')
85 | }).toThrow()
86 | })
87 |
88 | it('should throw error if translate keyword is missing in the language file', function () {
89 | expect(() => {
90 | i18n.t('five')
91 | }).toThrow()
92 | })
93 | })
94 | })
95 |
--------------------------------------------------------------------------------
/packages/react/README.md:
--------------------------------------------------------------------------------
1 | *Use of this software is subject to important terms and conditions as set forth in the License file*
2 |
3 | # React App Scaffold
4 |
5 | ## Description
6 |
7 | This repo contains a scaffold to help developers build [apps for Zendesk products](https://developer.zendesk.com/apps/docs/apps-v2/getting_started).
8 |
9 | ## Getting Started
10 |
11 | ### Dependencies
12 |
13 | - [Node.js](https://nodejs.org/en/) >= 18.12.1
14 | - [Ruby](https://www.ruby-lang.org/) = 2.6.x
15 |
16 | ### Setup
17 |
18 | 1. Clone or fork this repo
19 | 2. Change (`cd`) into the `app_scaffolds/packages/react` directory
20 | 3. Run `pnpm install`
21 |
22 | To run your app locally in Zendesk, you need the latest [Zendesk CLI](https://github.com/zendesk/zcli).
23 |
24 | ### Running locally
25 |
26 | To serve the app to your Zendesk instance with `?zcli_apps=true`, follow the steps below based on your environment:
27 |
28 | #### Development Environment
29 |
30 | 1. Open a new terminal and run the command:
31 |
32 | ```
33 | pnpm run dev
34 | ```
35 |
36 | 2. Open another terminal in the `app_scaffolds/packages/react` directory and run:
37 |
38 | ```
39 | pnpm run start
40 | ```
41 |
42 | > **Note:** Running the `pnpm run dev` command enables Hot Module Replacement (HMR), which allows you to see the changes you make to your code immediately without having to manually refresh the page. This greatly enhances the development experience.
43 |
44 | #### Production Environment
45 |
46 | 1. Open a new terminal and run the command:
47 |
48 | ```
49 | pnpm run build
50 | ```
51 |
52 | 2. Open another terminal in the `app_scaffolds/packages/react` directory and run:
53 |
54 | ```
55 | pnpm run start:prod
56 | ```
57 |
58 | ## But why?
59 |
60 | The App Scaffold includes many features to help you maintain and scale your app. Some of the features provided by the App Scaffold are listed below. However, you don't need prior experience in any of these to be able to use the scaffold successfully.
61 |
62 | - [ECMAScript](https://esbuild.github.io/content-types/#javascript) (ES2022)
63 |
64 | Vite supports the latest ECMAScript standards, including ES2022. This allows you to use modern JavaScript features such as class static initialization blocks, private instance methods and fields, the `at` method for arrays, public instance fields, top-level `await`, `Object.hasOwn`, and many more. Vite uses ESBuild for [fast transpilation](https://esbuild.github.io/) and Rollup for efficient module bundling and performance optimization. ESBuild ensures compatibility with the latest ECMAScript features for an enhanced development experience.
65 |
66 | - [Zendesk Garden](https://garden.zendesk.com/) React UI components
67 |
68 | Collection of React components optimized for Zendesk products, designed to handle a range of user input devices and support right-to-left layouts, with subtle animations for enhanced user experience.
69 |
70 | - [Vite](https://vitejs.dev/) with Rollup under the hood
71 |
72 | Vite leverages Rollup as its underlying bundler for fast, efficient module bundling and serving of your web application. It enhances development speed with lightning-fast hot module replacement (HMR) and optimized build performance.
73 |
74 | - [PostCSS](https://postcss.org/) stylesheets
75 |
76 | PostCSS transforms your stylesheets using JavaScript plugins, supporting CSS linting, variables, mixins, future syntax transpilation, and image inlining among other features, seamlessly integrated into Vite for enhanced CSS development workflow.
77 |
78 | - [Optimized Build](https://vitejs.dev/guide/build.html)
79 |
80 | Vite provides optimized production builds with features like code splitting, tree shaking, and pre-bundling, ensuring fast and efficient deployment of your application.
81 |
82 | - [Vitest](https://github.com/vitejs/vitest) JavaScript testing framework
83 |
84 | Vitest, built for Vite, is used for unit and integration testing of your application. It integrates seamlessly with Vite's testing ecosystem, offering efficient and reliable test coverage for your codebase.
85 |
86 | ## Folder structure
87 |
88 | The folder and file structure of the App Scaffold is as follows:
89 |
90 | | Name | Description |
91 | | :----------------------------- | :------------------------------------------------------------------------------------------- |
92 | | [`.github/`](#.github) | The folder to store PULL_REQUEST_TEMPLATE.md, ISSUE_TEMPLATE.md and CONTRIBUTING.md, etc |
93 | | [`dist/`](#dist) | The folder in which vite packages the built version of your app |
94 | | [`spec/`](#spec) | The folder in which all of your test files live |
95 | | [`src/`](#src) | The folder in which all of your source JavaScript, CSS, templates and translation files live |
96 | | [`rollup/`](#src) | static-copy-plugin and translations-loader-plugin to support i18n in the application |
97 | | [`vite.config.js`](#vite) | Configuration file for vite |
98 | | [`package.json`](#packagejson) | Configuration file for Project metadata, dependencies and build scripts |
99 |
100 | #### dist
101 |
102 | The dist directory is created when you run the app building scripts. You will need to package this folder when submitting your app to the Zendesk Apps Marketplace. It is also the folder you will have to serve when using [ZCLI](https://developer.zendesk.com/documentation/apps/app-developer-guide/zcli/). It includes your app's manifest.json file, an assets folder with all your compiled JavaScript and CSS as well as HTML and images.
103 |
104 | #### spec
105 |
106 | The spec directory is where all your tests and test helpers live. Tests are not required to submit/upload your app to Zendesk and your test files are not included in your app's package; however, it is good practice to write tests to document functionality and prevent bugs.
107 |
108 | #### src
109 |
110 | The src directory is where your raw source code lives. The App Scaffold includes different directories for JavaScript, stylesheets, templates, images, and translations. Most of your additions will be in here (and spec, of course!).
111 |
112 | #### vite.config.js
113 |
114 | `vite.config.js` is the configuration file for [Vite](https://vitejs.dev/). Vite is a fast build tool that leverages ESBuild for transpilation and Rollup for bundling. This file includes configurations for building, testing, and other customizations.
115 |
116 | - You can modify ESBuild settings directly within this file to adjust transpilation options. For more information, see the [Vite documentation on ESBuild](https://vitejs.dev/config/#esbuild).
117 |
118 | - **Static Copy Plugin**: This plugin is used to copy static assets to the `dist` directory during the build process.
119 | - **Translations Loader Plugin**: This plugin processes translation files at build time, converting `.json` translation files to JavaScript objects for the app.
120 |
121 | #### package.json
122 |
123 | package.json is the configuration file for [pnpm](https://pnpm.io/), which is a package manager for JavaScript. This file includes information about your project and its dependencies. For more information on how to configure this file, see [pnpm package.json](https://pnpm.io/package_json).
124 |
125 | ### I18n
126 |
127 | The I18n (internationalization) module in `/src/lib/i18n.js` provides a `t` method to look up translations based on a key. For more information, see [Using the I18n module](https://github.com/zendesk/app_scaffolds/blob/master/packages/react/doc/i18n.md).
128 |
129 | ## Parameters and Settings
130 |
131 | If you need to test your app with a `parameters` section in `dist/manifest.json`, foreman might crash with a message like:
132 |
133 | > Would have prompted for a value interactively, but zcli is not listening to keyboard input.
134 |
135 | To resolve this problem, set default values for parameters or create a `settings.yml` file in the root directory of your app scaffold-based project, and populate it with your parameter names and test values. For example, using a parameters section like:
136 |
137 | ```json
138 | {
139 | "parameters": [
140 | {
141 | "name": "myParameter"
142 | }
143 | ]
144 | }
145 | ```
146 |
147 | create a `settings.yml` containing:
148 |
149 | ```yaml
150 | myParameter: 'some value!'
151 | ```
152 |
153 | ## Testing
154 |
155 | The App Scaffold is currently setup for testing with [Vitetest](https://vitest.dev/). To run specs, open a new terminal and run
156 |
157 | ```
158 | pnpm run test
159 | ```
160 |
161 | Specs live under the `spec` directory.
162 |
163 | ## Deploying
164 |
165 | To check that your app will pass the server-side validation check, run
166 |
167 | ```
168 | zcli apps:validate dist
169 | ```
170 |
171 | If validation is successful, you can upload the app into your Zendesk account by running
172 |
173 | ```
174 | zcli apps:create dist
175 | ```
176 |
177 | To update your app after it has been created in your account, run
178 |
179 | ```
180 | zcli apps:update dist
181 | ```
182 |
183 | Or, to create a zip archive for manual upload, run
184 |
185 | ```
186 | zcli apps:package dist
187 | ```
188 |
189 | taking note of the created filename.
190 |
191 | For more information on the Zendesk CLI please see the [documentation](https://developer.zendesk.com/documentation/apps/app-developer-guide/zcli/).
192 |
193 | ## Contribute
194 |
195 | - Put up a PR into the master branch.
196 | - CC and get a +1 from @zendesk/wattle.
197 |
198 | ## Bugs
199 |
200 | Submit Issues via [GitHub](https://github.com/zendesk/app_scaffolds/issues/new) or email support@zendesk.com.
201 |
202 | ## Useful Links
203 |
204 | Links to maintaining team, confluence pages, Datadog dashboard, Kibana logs, etc
205 |
206 | - https://developer.zendesk.com/
207 | - https://github.com/zendesk/zendesk_apps_tools
208 | - https://esbuild.github.io/
209 | - https://vitejs.dev/
210 | - https://developer.zendesk.com/documentation/apps/build-an-app/using-react-in-a-support-app/
211 |
212 | ## Copyright and license
213 |
214 | Copyright 2018 Zendesk
215 |
216 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
217 |
218 | You may obtain a copy of the License at
219 | http://www.apache.org/licenses/LICENSE-2.0
220 | Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
221 |
--------------------------------------------------------------------------------
/packages/react/LICENSE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "{}"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright {yyyy} {name of copyright owner}
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
16 | 
21 |