Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New: astro add support instructions for integrations and adapters #946

Merged
merged 11 commits into from
Jul 12, 2022

Conversation

bholmesdev
Copy link
Contributor

What kind of changes does this PR include?

  • Minor content fixes (broken links, typos, etc.)
  • New or updated content
  • Translated content
  • Changes to the docs site code
  • Something else!

Description

  • Add "installation via astro add" instructions for integration authors
  • Add "installation via astro add" instructions for adapter authors

@bholmesdev bholmesdev changed the title New: add astro add support instructions for integrations and adapters New: astro add support instructions for integrations and adapters Jul 7, 2022
@netlify
Copy link

netlify bot commented Jul 7, 2022

Deploy Preview for astro-docs-2 ready!

Name Link
🔨 Latest commit 3983c4a
🔍 Latest deploy log https://app.netlify.com/sites/astro-docs-2/deploys/62cc7c95837aaa0008e06db5
😎 Deploy Preview https://deploy-preview-946--astro-docs-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Copy link
Member

@yanthomasdev yanthomasdev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this @bholmesdev! I added a few suggestions 🙌

Comment on lines 177 to 180
+ import myadapter from 'myadapter';

export default defineConfig({
+ adapter: myadapter(),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are using a specific pattern of camelCase and kebab-case in the SSR page and this pattern is also used in the Netlify Edge Functions adapter ('@astrojs/netlify/edge-functions'). I think it would be nice to use the same pattern everywhere in the docs, what do you think? This need to be changed in a few other places, I'm going to add the changes as suggestions.

Suggested change
+ import myadapter from 'myadapter';
export default defineConfig({
+ adapter: myadapter(),
+ import myAdapter from 'my-adapter';
export default defineConfig({
+ adapter: myAdapter(),

Copy link
Contributor Author

@bholmesdev bholmesdev Jul 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Yan-Thomas This sadly does NOT work! astro add will actually set the following when using dashes:

import my from 'my-adapter'

This avoids logging such a shortcoming. I had your solution before testing and discovering this. I know, it's annoying 😓

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's unfortunate! 😢 This means we need to change the pages in where we use this pattern then, I can take care of this tomorrow, thanks for testing and finding this behavior!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh boy, good to know! Tbh, I’d rather fix the underlying behavior before editing the docs. Hoping it’s easy to solve 😄 Hang tight!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just checking, but it seems all of our own adapters and integrations are all single words... so I guess we don't have this issue (of which case to use) when describing any of our own. It seems to only be an issue to document right now because we're trying to use a 2-word phrase "my adapter."

Is there a one-word, generic term that fits so that we avoid the issue? (That isn't "adapter"? 😅 )

Do we provide any suggestions for people naming their own? Is anyone likely to run into a problem choosing a particular multi-word name?

Otherwise, LGTM when you both are happy with the generic placeholder name!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sarah11918 Think I'll just use example to fix it 🙃

src/pages/en/reference/adapter-reference.md Outdated Show resolved Hide resolved
src/pages/en/reference/adapter-reference.md Outdated Show resolved Hide resolved
src/pages/en/reference/integrations-reference.md Outdated Show resolved Hide resolved
src/pages/en/reference/integrations-reference.md Outdated Show resolved Hide resolved
src/pages/en/reference/integrations-reference.md Outdated Show resolved Hide resolved
@sarah11918 sarah11918 added the add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. label Jul 9, 2022
@bholmesdev bholmesdev force-pushed the edit/add-integration-tagging-instructions branch from 8779e84 to 2e5473b Compare July 11, 2022 19:33
Copy link
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, Ben!

Non-blocking but couple of questions:

  • Is there a reason the adapter reference doesn’t include the same warning as the integrations reference re: default exports? From what I can see, the same seems like it would apply.

  • Do you think it would make sense to link to these from the “Publish to NPM” page? Like

    :::tip
    Want to support `astro add`? See instructions for adding `astro add` support to third-party [integrations](#) and [adapters](#).
    :::

@bholmesdev
Copy link
Contributor Author

@delucis That's because we don't update your config for third party adapters! As noted at the end, users are instructed to update their config manually.

@bholmesdev bholmesdev merged commit b5388c0 into main Jul 12, 2022
@bholmesdev bholmesdev deleted the edit/add-integration-tagging-instructions branch July 12, 2022 02:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
add new content Document something that is not in docs. May require testing, confirmation, or affect other pages.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants